Download OpenAPI specification:Download
The Metasys REST API is the exposed interface for accessing data from a Johnson
Controls® Metasys system. This spec documents v5 of the API first
released as part of Metasys 13.0. This documentation was last
updated on June 25, 2024 at 2:12 PM (UTC).
Note
The Metasys REST API is only supported on the following Metasys products: ADS, ADX, and OAS. The REST API is not supported on Metasys for Validated Environments (MVE) sites. Do not attempt to use the REST API on an MVE site.
This version of the documentation includes INTERNAL operations which are only for use by approved Johnson Controls teams/projects.
This version of the documentation includes PRIVATE operations which are only to be used by Metasys developers for Metasys products. These operations should not be shared with other teams within Johnson Controls, nor should they be shared with third parties outside of Johnson Controls.
Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.
This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.
© 2022 Johnson Controls Tyco IP Holdings LLP.
This documentation is for Metasys 13.0 which ships with version 5 of the Metasys Server.
The base path for the API is https://{hostname}/api/v5 where {hostname} is the host name of
your Metasys server.
Multiple versions of this API may be supported on one release of Metasys. At
Metasys 13.0, the supported versions are v4 and v5.
(However, v4 is deprecated and may be removed in a future release.)
Note: Versions earlier than v4 are not available on Metasys
13.0.
You must specify which version you intend to use in the URL, using the format
v[#].
For example, https://localhost/api/v5/spaces for version
5 of spaces.
Documentation for v3 and earlier can be found
here.
The Content-Type header of the response will always contain (in part) the
version of the API that was used to serve the request. This allows you to
identify which version of the API was utilized.
For example, Content-Type: application/vnd.metasysapi.v5+json for version
5.
You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).
The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).
The following operations require the Monitoring and Commanding API license:
In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:
presentValue. It is case sensitive and must always be
spelled presentValue.reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1,
and writePriorityEnumSet.priorityDefault).For operations where page and pageSize is allowed, the default page number
will be 1 and is 1-based for all paths while the default pageSize will vary
between paths. The page parameter indicates the page number of items to return
from the path. The pageSize parameter indicates the maximum number of items in
the response from the path.
Payloads returned by pagination-enabled paths have a similar structure. A
total property indicates the total number of items included in all pages. A
next and previous property supplies a link to the next and previous page of
data, respectively. These properties can be empty if irrelevant (for example, if
it is the first/last page, or there is only one page of data). The items
property contains the data included in the page.
For operations where a sort query parameter is allowed, the supplied value
should be in the format of a single attribute name, optionally prefixed with -
to indicate descending sort order (ascending order is used if no prefix is
supplied).
Payloads may contain links to related data, each represented as a property sharing the name of the respective relationship. The links point to either single or multiple related entities. A link to a single entity points to the canonical path for that entity. A link to multiple entities points to a path dedicated to representing that particular relationship.
For example, if object /objects/a has children /objects/b and /objects/c,
the payload returned by /objects/a will have a property objects with a value
of /objects/a/objects, because multiple children can be returned. However, the
payload returned by /objects/b/ will contain a property parent with a value
of /objects/a (not /objects/b/parent), because the relationship represents a
single entity.
Additionally, each payload contain a self property, which contains a link
representing the path used to obtain the data contained in the current payload.
All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.
There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.
| Condition | Error | Details |
|---|---|---|
| Invalid request body | 400 (Bad Request) | A body is provided which does not adhere to the expected format and/or schema |
| Missing required parameter | 400 (Bad Request) | A parameter marked required in this document is not included in the request |
| Parameter incorrect type | 400 (Bad Request) | A parameter is included with a value of the wrong type (for example, number is expected and string is provided) |
| Parameter out of range | 400 (Bad Request) | A numeric parameter is included but the value is outside the allowed range |
| Parameter not in set | 400 (Bad Request) | A string parameter has a set of predefined valid values, and the value provided is not included in that set |
| Parameter not in correct format | 400 (Bad Request) | A string parameter with expected format is provided in the wrong format |
Unsupported Content-Type |
400 (Bad Request) | An unsupported Content-Type header is provided |
| User not authenticated | 401 (Unauthorized) | The auth token supplied with the request is missing, invalid, or expired |
| Record not authorized | 403 (Forbidden) | The user is not authorized to view data matching the provided identifier or too many requests |
| Invalid user type | 403 (Forbidden) | Not an "API user"; not all user accounts have API access |
| API version not supported for MVE | 403 (Forbidden) | An operation was attempted against a validated resource using a version of an API not supported for MVE |
| Identifier not found | 404 (Not Found) | An identifier is provided that does not match any known data |
| The resource already exists | 409 (Conflict) | The resource already exists |
| Internal Server Error | 500 (Internal Server Error) | An unexpected error occurred |
| The device is not supported | 501 (Not Implemented) | The server does not support the functionality required to fulfill the request |
| A service is unavailable | 503 (Service Unavailable) | A service is currently unavailable to service the request. |
| The device is offline | 504 (Bad Gateway) | An attempt was made to talk to another device that is currently offline. |
The response payload of some operations in this document have a section of
information labeled schema. This section of information includes important
pieces of metadata about the item or items attributes that gives better
context to the meaning of attribute values. This section follows
JSON Schema specification with added custom
annotation keywords.
Most of the calls in the API use bearer token authentication. What this
means is that these requests require an Authorization header to be set to
a value with the following format: Bearer: {accessToken}. Use the
/login operation to request an accessToken. An
example of the full header would look like the following:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1....
Note: This example access token is truncated.
The expiration time of the access token is based on the user's Metasys profile.
bearerJWTThe Streaming operation is the only operation to use API key authentication, because web browsers do not allow setting custom headers when initiating Server Sent Event connections.
access_tokenThis section describes the operations you can perform on activities. Activities are a superset of all alarms and audits in a Metasys system. Use activities operations to view audits and alarms. Apply filters to further refine the results.
Subscribe for activity-related events to receive updates when activities are created, discarded, acknowledged, or annotated.
To subscribe for activity-related events, complete the following steps:
METASYS-SUBSCRIBE header with the stream ID.Note: Any filters added to the original GET operation also apply the event
subscription.
To unsubscribe from an activities event subscription, complete the following steps:
METASYS-SUBSCRIPTION-LOCATION from the subscribe operation
response.METASYS-SUBSCRIPTION-LOCATION.See also:
There are five event types sent by the activities subscription: acknowledged, annotate, discard, new, and heartbeat.
activity.heartbeat - A heartbeat event is sent to show that the subscription
is still alive. A heartbeat is a JSON string with the current UTC date time in
ISO 8601 format and is sent every 30 seconds.
{
"currentTime": "2021-02-16T16:21:10.23Z",
"subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
}
activity.alarm.ack - An alarm acknowledge event is sent to indicate that the
management status has changed to acknowledged.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "acknowledged",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "Engine1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"acknowledgedTime": "2021-02-16T20:31:02Z",
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.alarm.annotate - An alarm annotate event is sent when an annotation
is added to an alarm activity, providing the information for the annotated
alarm.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "Engine1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"acknowledgedTime": "2021-02-16T20:31:02Z",
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.alarm.discard - An alarm discard event is sent when the management
status of an alarm activity changes to discarded.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "discarded",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "Engine1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"acknowledgedTime": "2021-02-16T20:31:02Z",
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.alarm.new - A new alarm event is sent when an alarm activity is
created.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "IDU1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.audit.new - A new audit event is sent when an audit activity is
created.
{
"subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
"activity": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"itemReference": "{hostname}:{deviceHostname}",
"objectName": "MS-NAE5510-3",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T16:21:10.23Z",
"objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
"objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
"audit": {
"actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
"status": null,
"preData": null,
"postData": {
"item": "10.10.198.131",
"schema": {
"type": "string",
"metasysType": "string"
}
},
"parameters": [],
"errorString": null,
"user": "MetasysSysAgent",
"signature": null,
"classLevel": "auditClassesEnumSet.userActionAuditClass",
"originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
"description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
"annotationsUrl": null,
"self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
}
},
"effectivePermission": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"canDiscard": true
}
}
activity.audit.annotate - An annotate audit event is sent when an annotation
is added to an audit activity, providing the information for the annotated
audit.
{
"subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
"activity": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"itemReference": "{hostname}:{deviceHostname}",
"objectName": "MS-NAE5510-3",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T16:21:10.23Z",
"objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
"objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
"audit": {
"actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
"status": null,
"preData": null,
"postData": {
"item": "10.10.198.131",
"schema": {
"type": "string",
"metasysType": "string"
}
},
"parameters": [],
"errorString": null,
"user": "MetasysSysAgent",
"signature": null,
"classLevel": "auditClassesEnumSet.userActionAuditClass",
"originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
"description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
}
},
"effectivePermission": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"canDiscard": true
}
}
activity.audit.discard - An audit discard event is sent when the management
status of an audit activity changes to discarded.
{
"subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
"activity": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"itemReference": "{hostname}:{deviceHostname}",
"objectName": "MS-NAE5510-3",
"activityManagementStatus": "discarded",
"creationTime": "2021-02-16T16:21:10.23Z",
"objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
"objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
"audit": {
"actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
"status": null,
"preData": null,
"postData": {
"item": "10.10.198.131",
"schema": {
"type": "string",
"metasysType": "string"
}
},
"parameters": [],
"errorString": null,
"user": "MetasysSysAgent",
"signature": null,
"classLevel": "auditClassesEnumSet.userActionAuditClass",
"originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
"description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
}
},
"effectivePermission": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"canDiscard": true
}
}
Filters supplied to an activities request limit the results to activities for
which the filters apply. When subscribing to an activities request that uses
filters, the events received are also limited to the same filter criteria.
Exceptions to this behavior occur when filtering on activity management status,
such as for acknowledged or discarded activities. You receive an update
whenever an activity management change occurs, regardless of filters, because
the change can impact the original set of activities you subscribed to. For
example, consider the following scenario:
acknowledged activities and receive all acknowledged
activities, receiving updates for any acknowledged thereafter across the
stream.discarded by
another user.When this occurs, you receive an activity.alarm.discard message for the
discarded activity even though your filters exclude activities that are
discarded. This is necessary so that you can properly maintain the state of
activities already received in your application.
The priority alarm is the newest, highest priority alarm that is pending required acknowledgement by the current user. A user can subscribe to receive the initial and all subsequent changes to the current priority alarm and total pending acknowledgement alarm count over streaming notifications.
To subscribe for priority alarm notifications, complete the following steps:
To unsubscribe from a priority alarm subscription, complete the following steps:
Location from the subscribe operation response.Location.See also:
There are two event types sent by the priority alarm subscription:
activities.priorityAlarm.heartbeat - A heartbeat event is sent to show that
one or more subscriptions are still alive. A heartbeat is a JSON string with
the current UTC date time in ISO 8601 format and is sent every 30 seconds.| currentTime required | string <date-time> Current server time in ISO8601 format |
| subscriptionIds required | Array of strings List of all active subscriptionIds for this stream |
{- "currentTime": "2022-01-01T00:00:00Z",
- "subscriptionIds": [
- "34a22b98-9bfc-41d3-a275-933e5977c447"
]
}activities.priorityAlarm.update - An update event is sent when the current
priority alarm changes and/or the total pending acknowledgement alarm count
changes| subscriptionIds required | Array of strings <uuid> [ items <uuid > ] Subscription IDs that the notification apply to |
| total required | integer <int32> Total alarms pending acknowledgement |
object or null Current priority alarm. If null and |
{- "subscriptionIds": [
- "34a22b98-9bfc-41d3-a275-933e5977c447"
], - "total": 5,
- "item": {
- "id": "cedcf9f2-5ee5-445a-8f27-86997e3f7bc5",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "description": "Analog Value",
- "name": "AV1",
- "associatedGraphic": {
- "reference": {
- "objectReference": "{hostname}:{deviceHostname}"
}, - "alias": "AV*"
}, - "message": "Alarm message",
- "type": "alarmValueEnumSet.avHiAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2022-08-15T18:39:50Z",
}
}Retrieves a collection of activities.
| activityType | Array of strings[ items <= 2 items ] Items Enum: "alarm" "audit" Example: activityType=alarm Limit the activities returned to a specific type |
| includeDiscarded | boolean Determines whether discarded activities will be included in the results or
be the only type of activity in the results. Discarded activities are those
for which the This parameter can produce 3 different types of results.
|
| continuationToken | string Example: continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM... Provide a token from a previous request to fetch the next set of results. Ignored for streaming subscriptions. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether activities which can be acknowledged are included in the
results. When the value is The use of this parameter implies a filter of |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether activities which can not be acknowledged are included in
the results. When the value is The use of this parameter implies a filter of |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| originApplication | Array of strings Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp metasysEnum: auditOriginAppEnumSet Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message. The acceptable values for the elements of this parameter come from the See also:
|
| classLevel | Array of strings Example: classLevel=auditClassesEnumSet.userActionAuditClass metasysEnum: auditClassesEnumSet Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose. The Enabled Audit Level attribute ( The acceptable values for the elements of this parameter come from the See also:
|
| actionType | Array of strings Example: actionType=auditActionTypeEnumSet.writeAuditActionType metasysEnum: auditActionTypeEnumSet Filter by list of action types. The action type property indicates the user or system action performed. The acceptable values for the elements of this parameter come from the See also:
|
| user | Array of strings <= 100 items Example: user=metasysuser Filter by list of users. The user property indicates which user initiated the action being audited. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/activities?activityType=alarm&includeDiscarded=false&continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...&sort=creationTime&startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
{- "total": 4096,
- "items": [
- {
- "id": "648070d6-3b00-4027-ad07-63e9247f4e40",
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Site Director",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:16:33.403Z",
- "objectId": "c05d5d30-ebf0-5533-8e67-f74bb728bf18",
- "discardedTime": null,
- "audit": {
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "jane-doe",
- "signature": null,
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
- "annotationsUrl": "https://{hostname}/api/v5/audits/648070d6-3b00-4027-ad07-63e9247f4e40/annotations",
- "annotationsCount": 0,
}
}, - {
- "id": "bf350492-bf03-43d5-8c50-6d9727e420fe",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "objectName": "AV1",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:16:18Z",
- "discardedTime": null,
- "equipment": [
- {
- "id": "ef24e09e-fc26-5113-b91e-607dd6f81b93",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 1",
- "equipmentName": "My Engine 1",
- "shortName": "My Engine 1.AV1",
}
], - "objectId": "559081e4-4ddd-5923-ab03-85c1797126a5",
- "alarm": {
- "message": "",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV1.Alarm1",
- "referencedObject": {
}
}, - "isAckRequired": true,
- "type": "alarmValueEnumSet.avHiAlarm",
- "priority": 100,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsCount": 1,
- "triggerValue": {
- "item": "82.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}
}
}, - "description": "Zone Temperature",
- "acknowledgedTime": null,
- "associatedGraphic": null
}
}
], - "effectivePermissions": [
- {
- "id": "648070d6-3b00-4027-ad07-63e9247f4e40",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "bf350492-bf03-43d5-8c50-6d9727e420fe",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}
],
}Used to invoke multiple activity operations in a single HTTP request. In this version of the API, the only activity-related operations that can be used in a batch are listed below.
See also
| method required | string Enum: "PATCH" "POST" The HTTP method to use for each request. |
required | Array of objects A collection of entries that represent the operations to invoke. |
A request to discard multiple activities (2 audits and 2 alarms). One audit request and one alarm request include annotation text and the other requests do not.
{- "method": "PATCH",
- "requests": [
- {
- "id": "1",
- "body": {
- "activityManagementStatus": "discarded",
- "annotationText": "Issue resolved"
}
}, - {
- "id": "2",
- "body": {
- "activityManagementStatus": "discarded"
}
}, - {
- "id": "3",
- "body": {
- "activityManagementStatus": "discarded",
- "annotationText": "Issue resolved"
}
}, - {
- "id": "4",
- "body": {
- "activityManagementStatus": "discarded"
}
}
]
}This is an example response to a batch request. Two of the operations succeeded and two of them failed.
{- "responses": [
- {
- "id": "1",
- "status": 204
}, - {
- "id": "2",
- "status": 400
}, - {
- "id": "3",
- "status": 204
}, - {
- "id": "4",
- "status": 400
}
]
}Deletes a subscription to the activities resource.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/activities/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Creates a subscription to receive the current and all subsequent changes to the priority alarm and total pending acknowledgement alarm count. If the provided streamId is not valid or authorized, you will not receive an error nor would you receive any stream notifications.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
curl --request POST \ --url https://metasys-server.example.com/api/v5/activities/priorityAlarm/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Deletes a subscription to the current priority alarm.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/activities/priorityAlarm/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.
Retrieves a collection of alarms for the specified object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeDiscarded | boolean Determines whether discarded alarms will be included in the results or be
the only type of alarm in the results. Discarded alarms are those for which
the
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether alarms which can be acknowledged are included in the results. When the value is |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether alarms which can not be acknowledged are included in the results. When the value is |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 403,
- "previous": null,
- "items": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
], - "discardedTime": null,
- "acknowledgedTime": null,
- "associatedGraphic": null,
- "alarmGeneratorObject": null
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
], - "discardedTime": null,
- "acknowledgedTime": null,
- "associatedGraphic": null
}
], - "effectivePermissions": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}
],
}Retrieves a collection of alarms for the specified network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeDiscarded | boolean Determines whether discarded alarms will be included in the results or be
the only type of alarm in the results. Discarded alarms are those for which
the
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether alarms which can be acknowledged are included in the results. When the value is |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether alarms which can not be acknowledged are included in the results. When the value is |
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 9027,
- "previous": null,
- "items": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
], - "discardedTime": null,
- "acknowledgedTime": null,
- "associatedGraphic": null,
- "alarmGeneratorObject": null
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "jciSystemStatusEnumSet.jciOperational",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:02:03Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null,
- "discardedTime": null,
- "acknowledgedTime": null,
- "associatedGraphic": null,
- "alarmGeneratorObject": null
}
], - "effectivePermissions": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}
], - "networkDeviceUrl": "https://{hostname}/api/v5/networkDevices/088333f5-f76e-5177-85aa-73aa32f1c8b3",
}Retrieves a collection of alarms.
Note: This operation is deprecated and may be removed in a future release. To retrieve alarms, consider using
GET /activities?activityType=alarminstead. See List activities
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeDiscarded | boolean Determines whether discarded alarms will be included in the results or be
the only type of alarm in the results. Discarded alarms are those for which
the
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether alarms which can be acknowledged are included in the results. When the value is |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether alarms which can not be acknowledged are included in the results. When the value is |
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 10154,
- "previous": null,
- "items": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
], - "discardedTime": null,
- "acknowledgedTime": null,
- "associatedGraphic": null,
- "alarmGeneratorObject": null
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "jciSystemStatusEnumSet.jciOperational",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:02:03Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null,
- "discardedTime": null,
- "acknowledgedTime": null,
- "associatedGraphic": null,
- "alarmGeneratorObject": null
}
], - "effectivePermissions": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}
],
}Retrieves the specified alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
An alarm for an analog value object.
{- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "discardedTime": null,
- "acknowledgedTime": null,
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
], - "associatedGraphic": null,
- "alarmGeneratorObject": null
}Allows for acknowledging or discarding an alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
| activityManagementStatus required | string Enum: "acknowledged" "discarded" The new activity management status of the alarm. The values of this property are described as follows:
|
| annotationText | string or null The annotation associated with the change of alarm state. |
{- "activityManagementStatus": "acknowledged"
}{- "code": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Retrieves the collection of annotations available for the specified alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "user" "-user" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 1,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": 1,
- "text": "Looks okay",
- "user": "jane-doe",
- "creationTime": "2021-09-28T17:11:57.95Z",
- "action": "acknowledged",
}
],
}Adds an annotation to an alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
| text required | string [ 1 .. 255 ] characters \S The text of the annotation to create. This must not be |
{- "text": "Looks okay."
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Gets the current announcements
curl --request GET \ --url https://metasys-server.example.com/api/v5/announcements \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "type": "announcement",
- "label": "Announcement",
- "totalCount": 0,
- "announcements": [ ]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Create an announcement
| label required | string |
| enabled | boolean |
| description required | string |
| startDateTime required | string <date-time> |
| endDateTime | string <date-time> |
| toEmailAddresses required | Array of strings <email> [ items <email > ] |
| announcementTypes required | Array of strings Items Enum: "loginScreen" "banner" "email" |
{- "label": "Important update",
- "description": "Please review all alarms",
- "startDateTime": "2023-07-01T10:00:00-6:00",
- "announcementTypes": [
- "loginScreen",
- "banner"
], - "toEmailAddresses": [ ]
}3Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| id required | integer |
| label required | string |
| enabled | boolean |
| description required | string |
| startDateTime required | string <date-time> |
| endDateTime | string <date-time> |
| toEmailAddresses required | Array of strings <email> [ items <email > ] |
| announcementTypes required | Array of strings Items Enum: "loginScreen" "banner" "email" |
{- "id": 5,
- "label": "Important update",
- "description": "Please review all alarms",
- "startDateTime": "2023-07-01T10:00:00-6:00",
- "announcementTypes": [
- "loginScreen",
- "banner"
], - "toEmailAddresses": [ ]
}3Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| announcementId | integer Example: 3 The id of the announcement |
curl --request GET \ --url https://metasys-server.example.com/api/v5/announcements/3 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "label": "Important update",
- "description": "Please review all alarms",
- "startDateTime": "2023-07-01T10:00:00-6:00",
- "announcementTypes": [
- "loginScreen",
- "banner"
], - "toEmailAddresses": [ ]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| announcementId required | integer Example: 3 The id of the announcement |
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/announcements/3 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
If no such announcement exists, then you'll get an announcement with default values for all of the properties.
| announcementType | string Enum: "loginScreen" "banner" "email" Example: loginScreen The announce type |
curl --request GET \ --url https://metasys-server.example.com/api/v5/announcements/loginScreen/latest \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This is an example of what this returns if there is no such announcement.
{- "id": 0,
- "type": "announcement",
- "label": null,
- "enabled": false,
- "description": null,
- "startDateTime": "0001-01-01T00:09:00-05:51",
- "endDateTime": null,
- "toEmailAddresses": null,
- "announcementTypes": null,
- "isCompleted": true
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Dismisses announcement for current user until announcement is updated again.
| announcementId | integer Example: 3 The announcement id |
curl --request POST \ --url https://metasys-server.example.com/api/v5/announcements/3/dismiss \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
5How to retrieve, discard, and annotate audits.
Audits have relationships to other resources in the system. Find information about the most important below.
When users or the system affect objects in the Metasys system, such as analog inputs, multistate objects, or binary outputs, audits are generated. Those "acted upon" objects then relate to those audits. That relationship is returned as part of any audit response.
Equipment instance associations to audits build off of the objects association explanation. Each equipment instance can contain many points, such as Outdoor Air Temperature, Damper Position, or Zone Setpoint. Those points map to actual objects in Metasys, as noted above. When users or the system affect those objects, audits are generated. If an equipment instance's point is mapped to one of those affected objects the instance is then associated with that audit.
In short, an equipment instance contains points which map to Metasys objects which are affected by an audited action.
Space associations to audits build off of the equipment instance association explanation. Equipment instances can serve spaces, such as an Air Handler Unit (AHU) serving the floor of a building. Therefore, audits associated with a particular equipment instance are associated to the spaces they serve.
Retrieves a collection of audits for the specified object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| originApplication | Array of strings Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp metasysEnum: auditOriginAppEnumSet Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message. The acceptable values for the elements of this parameter come from the See also:
|
| classLevel | Array of strings Example: classLevel=auditClassesEnumSet.userActionAuditClass metasysEnum: auditClassesEnumSet Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose. The Enabled Audit Level attribute ( The acceptable values for the elements of this parameter come from the See also:
|
| actionType | Array of strings Example: actionType=auditActionTypeEnumSet.writeAuditActionType metasysEnum: auditActionTypeEnumSet Filter by list of action types. The action type property indicates the user or system action performed. The acceptable values for the elements of this parameter come from the See also:
|
| user | Array of strings <= 100 items Example: user=metasysuser Filter by list of users. The user property indicates which user initiated the action being audited. |
| includeDiscarded | boolean Determines whether discarded audits will be included in the results.
|
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Gets the first 10 audits.
{- "total": 400,
- "previous": null,
- "items": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "creationTime": "2021-11-23T23:39:33.413Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "creationTime": "2021-11-23T23:39:27Z",
- "actionType": "auditActionTypeEnumSet.writeAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrUsageAnalyticsTermsAccepted"
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "creationTime": "2021-11-23T23:39:25.517Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "creationTime": "2021-11-23T23:39:19.29Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLogout"
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "creationTime": "2021-11-23T23:39:15.663Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "user: api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityPermissionsModified"
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "creationTime": "2021-11-23T23:39:15.633Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUpdateUserProperty"
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "creationTime": "2021-11-24T01:30:12.537Z",
- "actionType": "auditActionTypeEnumSet.commandAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": null,
- "postData": null,
- "parameters": [
- {
- "item": "resetReasonEnumSet.downloadCompleteResetReason",
- "schema": {
- "type": "string",
- "metasysType": "enum",
}
}
], - "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "commandIdEnumSet.resetCommand"
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "creationTime": "2021-11-23T23:38:37.117Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginFail"
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "creationTime": "2021-11-24T01:22:40Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "jciSystemStatusEnumSet.startupInProgress"
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "creationTime": "2021-11-24T01:13:39.36Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginFail"
}
], - "effectivePermissions": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "canDiscard": true,
- "canAnnotate": true
}
],
}Retrieves a collection of audits.
Note: This operation is deprecated and may be removed in a future release. To retrieve audits, consider using
GET /activities?activityType=auditinstead. See List activities
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| originApplication | Array of strings Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp metasysEnum: auditOriginAppEnumSet Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message. The acceptable values for the elements of this parameter come from the See also:
|
| classLevel | Array of strings Example: classLevel=auditClassesEnumSet.userActionAuditClass metasysEnum: auditClassesEnumSet Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose. The Enabled Audit Level attribute ( The acceptable values for the elements of this parameter come from the See also:
|
| actionType | Array of strings Example: actionType=auditActionTypeEnumSet.writeAuditActionType metasysEnum: auditActionTypeEnumSet Filter by list of action types. The action type property indicates the user or system action performed. The acceptable values for the elements of this parameter come from the See also:
|
| user | Array of strings <= 100 items Example: user=metasysuser Filter by list of users. The user property indicates which user initiated the action being audited. |
| includeDiscarded | boolean Determines whether discarded audits will be included in the results.
|
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Gets the first 10 audits.
{- "total": 400,
- "previous": null,
- "items": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "creationTime": "2021-11-23T23:39:33.413Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "creationTime": "2021-11-23T23:39:27Z",
- "actionType": "auditActionTypeEnumSet.writeAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrUsageAnalyticsTermsAccepted"
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "creationTime": "2021-11-23T23:39:25.517Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "creationTime": "2021-11-23T23:39:19.29Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLogout"
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "creationTime": "2021-11-23T23:39:15.663Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "user: api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityPermissionsModified"
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "creationTime": "2021-11-23T23:39:15.633Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUpdateUserProperty"
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "creationTime": "2021-11-24T01:30:12.537Z",
- "actionType": "auditActionTypeEnumSet.commandAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": null,
- "postData": null,
- "parameters": [
- {
- "item": "resetReasonEnumSet.downloadCompleteResetReason",
- "schema": {
- "type": "string",
- "metasysType": "enum",
}
}
], - "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "commandIdEnumSet.resetCommand"
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "creationTime": "2021-11-23T23:38:37.117Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginFail"
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "creationTime": "2021-11-24T01:22:40Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "jciSystemStatusEnumSet.startupInProgress"
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "creationTime": "2021-11-24T01:13:39.36Z",
- "actionType": "auditActionTypeEnumSet.createAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": null,
- "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "IntraComputer",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}/$GenericArchive.GraphicAssets.Shared.Template",
- "objectName": "Shared Template",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.generalAuditOriginApp",
- "description": null
}
], - "effectivePermissions": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "canDiscard": true,
- "canAnnotate": true
}
],
}Retrieves the specific audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
An audit for an analog value object.
{- "id": "6c6ae3dd-c514-423d-bd22-0b48678c5384",
- "creationTime": "2021-12-10T21:05:53Z",
- "actionType": "auditActionTypeEnumSet.commandAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "spaces": [ ],
- "equipment": [ ],
- "preData": {
- "item": 52,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}
}, - "postData": null,
- "parameters": [
- {
- "item": 50,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}, - "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}
}
], - "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "objectName": "Interlock1/AV1",
- "classLevel": "auditClassesEnumSet.applicationAuditClass",
- "originApplication": "auditOriginAppEnumSet.interlockAuditOriginApp",
- "description": "commandIdEnumSet.adjustCommand"
}Allows for discarding an audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
| activityManagementStatus required | string Value: "discarded" The new activity management status of the audit. The only accepted value of this property is |
| annotationText | string or null The annotation to associate with the change of audit state. |
{- "activityManagementStatus": "discarded"
}{- "code": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Retrieves the collection of annotations available for the specified audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 1,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": 2,
- "creationTime": "2021-09-28T19:00:48.043Z",
- "user": "jane-doe",
- "signature": null,
- "action": "discarded"
}
],
}Adds an annotation to an audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
| text required | string [ 1 .. 255 ] characters \S The text of the annotation to create. This must not be |
{- "text": "Looks okay."
}Retrieves a list of unique usernames from all users present in a currently stored audit. The provided usernames may or may not reflect known users of the current system, but were known when the system recorded an audit for them.
curl --request GET \ --url https://metasys-server.example.com/api/v5/audits/users \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- "aaron",
- "brian",
- "chris",
- "diana",
- "emily"
], - "total": 5,
}Gets counts of audits in specified time intervals for a given time period grouped by audit string ids (optionally grouped by specified time interval).
| auditActions | Array of integers Example: auditActions=41,42,107,150 Filter by audit strings. The values for this property come from the Find the definition of
See also:
|
| startTime required | string <date-time> Example: startTime=2022-07-21T10:00:00-05:00 Only include results generated on or after this date-time. |
| endTime required | string <date-time> Example: endTime=2022-07-22T09:08:59-05:00 Only include results generated on or before this date-time. |
| timeInterval | string Default: "None" Enum: "None" "Hour" "Day" "Week" "Month" Example: timeInterval=Hour A time interval in which audit counts will be grouped by. |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/audits/counts?auditActions=41%2C42%2C107%2C150&startTime=2022-07-21T10%3A00%3A00-05%3A00&endTime=2022-07-22T09%3A08%3A59-05%3A00&timeInterval=Hour' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
[- {
- "intervalStartTime": "2022-07-31T05:00:00Z",
- "intervalEndTime": "2022-08-01T05:00:00Z",
- "auditCounts": [
- {
- "id": 41,
- "count": 1
}, - {
- "id": 43,
- "count": 0
}, - {
- "id": 154,
- "count": 2
}
]
}, - {
- "intervalStartTime": "2022-08-01T05:00:00Z",
- "intervalEndTime": "2022-08-02T05:00:00Z",
- "auditCounts": [
- {
- "id": 41,
- "count": 7
}, - {
- "id": 43,
- "count": 2
}, - {
- "id": 154,
- "count": 2
}
]
}
]Use this to request an access token that can be used for authentication on other API calls.
Used to supply credentials for login.
| username | string The user name of an account. This can either be a local Metasys
account, or an Active Directory account that has been granted access
to Metasys. When using an Active Directory account, the value should
be in the format Note: Only accounts with an Access Type of |
| password | string The corresponding password of a Metasys account. |
{- "username": "jane-doe",
- "password": "strongPassword"
}The result includes the access token needed to make requests. (The token in this example has been truncated.)
{- "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
- "expires": "2021-04-22T00:12:18Z"
}Use this operation to request a new token before the previous one expires.
curl --request GET \ --url https://metasys-server.example.com/api/v5/refreshToken \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The result includes the access token needed to make requests. (The token in this example has been truncated.)
{- "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
- "expires": "2021-04-22T00:12:18Z"
}Use this to request a trusted peer access token that can be used for authentication on other API calls. This is intended for one service to call another without having to login as a user.
Used to supply credentials to request a trusted peer token.
| clientId | string The client id of the service that you are connecting to. |
| secret | string The corresponding secret used to verify that you should be granted access. |
{- "clientId": "Metasys.Server",
- "secret": "9d845ba5-d0c6-4f62-81dd-07b8fe31a68b"
}The result includes the access token needed to make requests. (The token in this example has been truncated.)
{- "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
- "expires": "2021-04-22T00:12:18Z"
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Gets the system settings related to Active Directory
curl --request GET \ --url https://metasys-server.example.com/api/v5/authenticationSettings/activeDirectory \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "activeDirectoryConfiguration": {
- "enableActiveDirectory": false,
- "enableSingleSignOn": false,
- "defaultLoginDomain": "metasys local"
}, - "serviceAccounts": [ ]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
object | |
Array of objects |
{- "activeDirectoryConfiguration": {
- "enableActiveDirectory": false,
- "enableSingleSignOn": false,
- "defaultLoginDomain": "metasys local"
}, - "serviceAccounts": [ ]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Gets the ADFS settings
curl --request GET \ --url https://metasys-server.example.com/api/v5/authenticationSettings/adfs \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "enabled": false,
- "ssoEnabled": false,
- "endPoint": null,
- "clientId": null
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| enabled | boolean |
| ssoEnabled | boolean |
| endPoint | string or null |
| clientId | string or null |
{- "enabled": false,
- "ssoEnabled": false,
- "endPoint": null,
- "clientId": null
}Retrieve the binary CSR data for a single device. A successful (200) response provides the CSR in a PEM format.
Note: This endpoint is intended to support
application/vnd.metasysapi.v5+json and application/octet-stream MIME types
via the Accept header however neither of these are currently supported.
Only application/pkcs10 is supported even though it shouldn't be.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| If-None-Match | string Example: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM= A previous |
curl --request GET \ --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'If-None-Match: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM='
A certificate signing request in PEM format meant for a raw output (a MIME
type of application/octet-stream).
-----BEGIN CERTIFICATE REQUEST----- MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3 NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8 SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3 4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx 2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA== -----END CERTIFICATE REQUEST-----
Create a new certificate signing request (CSR) for the specified device and CSR parameters. A successful (201) response provides the CSR in a PEM format.
Note: This endpoint is intended to support
application/vnd.metasysapi.v5+json and application/octet-stream MIME types
via the Accept header however neither of these are currently supported.
Only application/pkcs10 is supported even though it shouldn't be.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| emailAddress required | string <email> [ 1 .. 63 ] characters |
| orgName required | string [ 1 .. 63 ] characters |
| orgUnitName required | string [ 1 .. 63 ] characters |
| city required | string [ 1 .. 63 ] characters |
| stateProvince required | string [ 1 .. 63 ] characters |
| country required | string = 2 characters |
| domainName | string or null [ 1 .. 47 ] characters |
{- "city": "Milwaukee",
- "country": "US",
- "emailAddress": "noreply@jci.com",
- "orgName": "Johnson Controls",
- "orgUnitName": "BAS",
- "stateProvince": "WI",
- "domainName": "jci.com"
}A certificate signing request in PEM format meant for a raw output (a MIME
type of application/octet-stream).
-----BEGIN CERTIFICATE REQUEST----- MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3 NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8 SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3 4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx 2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA== -----END CERTIFICATE REQUEST-----
Replace the certificate signing request (CSR) for the specified device and CSR parameters. A successful (200) response provides the CSR in a PEM format.
Note: This endpoint is intended to support
application/vnd.metasysapi.v5+json and application/octet-stream MIME types
via the Accept header however neither of these are currently supported.
Only application/pkcs10 is supported even though it shouldn't be.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| If-Match required | string Example: 33a64df551425fcc55e4d42a148795d9f25f89d4 A previous |
| emailAddress required | string <email> [ 1 .. 63 ] characters |
| orgName required | string [ 1 .. 63 ] characters |
| orgUnitName required | string [ 1 .. 63 ] characters |
| city required | string [ 1 .. 63 ] characters |
| stateProvince required | string [ 1 .. 63 ] characters |
| country required | string = 2 characters |
| domainName | string or null [ 1 .. 47 ] characters |
{- "city": "Milwaukee",
- "country": "US",
- "emailAddress": "noreply@jci.com",
- "orgName": "Johnson Controls",
- "orgUnitName": "BAS",
- "stateProvince": "WI",
- "domainName": "jci.com"
}A certificate signing request in PEM format meant for a raw output (a MIME
type of application/octet-stream).
-----BEGIN CERTIFICATE REQUEST----- MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3 NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8 SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3 4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx 2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA== -----END CERTIFICATE REQUEST-----
Clear any existing certificate signing request (CSR) for the specified device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| If-Match required | string Example: 33a64df551425fcc55e4d42a148795d9f25f89d4 A previous |
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'If-Match: 33a64df551425fcc55e4d42a148795d9f25f89d4'
{- "statusName": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Retrieve the raw and/or structured certificate data for a single device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| flatten | boolean Default: true Example: flatten=true Return the certificates as a flat list or as nested trees. When nested, the result items will have an |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?flatten=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Certificate details as a list. Note that JSON must encode new lines (\n) for the raw property.
{- "items": [
- {
- "id": "7EEC06D24877B4D191FA463D358609CC20289D4F",
- "issuer": "CN=Metasys Test CA",
- "subject": "C=US, S=WI, L=MKE, O=JCI, OU=BE, CN=MAC02427035AC6D, E=test@testAll.com",
- "validFrom": "2021-04-19T22:06:37Z",
- "validUntil": "2022-03-30T19:45:10Z",
- "authorityKeyId": "4131D4F94A1D71243E624FFC20468F023440FA7A",
- "subjectKeyId": "2EE21E21D641AAA23042F20FE13FD12A95831A85",
- "serialNumber": "00B9431D8F2B149691",
- "raw": "-----BEGIN CERTIFICATE-----\nMIICJjCCAcugAwIBAgIJALlDHY8rFJaRMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT\nD01ldGFzeXMgVGVzdCBDQTAeFw0yMTA0MTkyMjA2MzdaFw0yMjAzMzAxOTQ1MTBa\nMH4xHzAdBgkqhkiG9w0BCQEWEHRlc3RAdGVzdEFsbC5jb20xGDAWBgNVBAMTD01B\nQzAyNDI3MDM1QUM2RDELMAkGA1UECxMCQkUxDDAKBgNVBAoTA0pDSTEMMAoGA1UE\nBxMDTUtFMQswCQYDVQQIEwJXSTELMAkGA1UEBhMCVVMwdjAQBgcqhkjOPQIBBgUr\ngQQAIgNiAARei12VLrNFW9ThXWbuP9jjgqumm+qRbYmjRr2Eft09gzcn9fSZyr7g\npmUZVsTeEbzzkAJDDFVobQ4iis5iXD8iAs/h4DkFc5eoXmS5hWGL3n5VPLfE1hCB\nD6HZCVGmd/6jeTB3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQULuIeIdZBqqIwQvIP4T/RKpWD\nGoUwHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaPAjRA+nowCgYIKoZIzj0EAwID\nSQAwRgIhAOBqzqlMJtoTvQxH0qx1s6oVY1NvsyXthO9SZlwlYEkeAiEAwyU0/jgU\nNaHD0eqyywHZxyQto1vTscCbTJZIuFOVGnk=\n-----END CERTIFICATE-----\n"
}, - {
- "id": "1535878BEAFA6F37273548BB0024FAE212C8759B",
- "issuer": "CN=Metasys Test CA",
- "subject": "CN=Metasys Test CA",
- "validFrom": "2021-03-29T19:45:10Z",
- "validUntil": "2022-03-30T19:45:10Z",
- "authorityKeyId": "4131D4F94A1D71243E624FFC20468F023440FA7A",
- "subjectKeyId": "4131D4F94A1D71243E624FFC20468F023440FA7A",
- "serialNumber": "00D5218FE0248E8D25",
- "raw": "-----BEGIN CERTIFICATE-----\nMIIBpzCCAU2gAwIBAgIJANUhj+Akjo0lMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT\nD01ldGFzeXMgVGVzdCBDQTAeFw0yMTAzMjkxOTQ1MTBaFw0yMjAzMzAxOTQ1MTBa\nMBoxGDAWBgNVBAMTD01ldGFzeXMgVGVzdCBDQTBZMBMGByqGSM49AgEGCCqGSM49\nAwEHA0IABDDE4n8dfuug8nHErsHyEGO6FQZ56Kyv+tCiUnDJpULs86y2/HXEejxr\ntU4UgTbt5YJCxu7cPI+TYmMfyjwG3WyjfDB6MAwGA1UdEwQFMAMBAf8wCwYDVR0P\nBAQDAgKkMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQU\nQTHU+UodcSQ+Yk/8IEaPAjRA+nowHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaP\nAjRA+nowCgYIKoZIzj0EAwIDSAAwRQIgH/C7cCPvP3kqVI0oSpKmRgQOJZOK+X9h\nZjtL1/6pPbsCIQDGIC2Y4jfEKvyFB1g1RIftdmOManZbbYb+6FTbWgczYA==\n-----END CERTIFICATE-----\n"
}
]
}Write the raw certificate data for a single device. The data may be a single operational certificate or the entire chain.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
A certificate in PEM format.
-----BEGIN CERTIFICATE----- MIICJjCCAcugAwIBAgIJALlDHY8rFJaRMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT D01ldGFzeXMgVGVzdCBDQTAeFw0yMTA0MTkyMjA2MzdaFw0yMjAzMzAxOTQ1MTBa MH4xHzAdBgkqhkiG9w0BCQEWEHRlc3RAdGVzdEFsbC5jb20xGDAWBgNVBAMTD01B QzAyNDI3MDM1QUM2RDELMAkGA1UECxMCQkUxDDAKBgNVBAoTA0pDSTEMMAoGA1UE BxMDTUtFMQswCQYDVQQIEwJXSTELMAkGA1UEBhMCVVMwdjAQBgcqhkjOPQIBBgUr gQQAIgNiAARei12VLrNFW9ThXWbuP9jjgqumm+qRbYmjRr2Eft09gzcn9fSZyr7g pmUZVsTeEbzzkAJDDFVobQ4iis5iXD8iAs/h4DkFc5eoXmS5hWGL3n5VPLfE1hCB D6HZCVGmd/6jeTB3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMB0GA1UdJQQWMBQG CCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQULuIeIdZBqqIwQvIP4T/RKpWD GoUwHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaPAjRA+nowCgYIKoZIzj0EAwID SQAwRgIhAOBqzqlMJtoTvQxH0qx1s6oVY1NvsyXthO9SZlwlYEkeAiEAwyU0/jgU NaHD0eqyywHZxyQto1vTscCbTJZIuFOVGnk= -----END CERTIFICATE-----
{- "statusName": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Delete the certificate(s) for a single device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| loose | boolean Default: true Example: loose=true If Note: Only |
curl --request DELETE \ --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?loose=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "statusName": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Write a collection of raw certificate data to the devices associated to the included certificates.
A ZIP file which must contain 1 or more operational certificates and their issuer certificate(s). The issuer certificate(s) may be a separate file or included with each operational certificate (known as a PKCS #7 file).
curl --request POST \ --url https://metasys-server.example.com/api/v5/networkDevices/certificates/bacnet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Import BACnet/SC certificates success response
[- {
- "certificate": "filename1.pem",
- "detectedType": "operational",
- "deviceId": "31469a3d-44da-4aa3-8f26-ec5753e0f23d",
- "status": "applied"
}, - {
- "certificate": "filename2.pem",
- "detectedType": "operational",
- "deviceId": null,
- "status": "deviceNotFound"
}, - {
- "certificate": "signing.pem",
- "detectedType": "issuer",
- "deviceId": null,
- "status": "issuer"
}
]Operations on control objects.
Some controls may have a visual representation known as a diagram. While a diagram is a visual representation, it is more importantly the means by which control logic is defined for some types of controls.
A diagram contains 3 general elements - blocks, ports, and connections.
A block generally represents some primitive function, such as an add operation. Most blocks work upon some number of input ports and provide the result via output ports. Blocks may have additional configuration to them as well.
The ports of blocks can be connected via connections to pass values from a source to a destination.
Every block in a diagram is defined by a schema. A schema defines what the available properties and ports are available on a block. The properties and ports have associated metadata to define value types and value constraints.
A block schema is a JSON Schema, with some custom keywords:
sequenceProperties - indicates that all properties defined under it should
be generated from a sequence of integer values. Every property name should be
a format string which includes {n} as a placeholder to where the sequence
number is populated. The source of the sequence numbering is defined by a
countSource property, which defines how many properties are currently
defined in the instance data that follow a templated sequence. This value
should resolve to a property of the block. The schema of the countSource
property should always be of type "integer", have a non-negative minimum,
and have a maximum.Diagrams may be subscribed to for streaming events by a client. A subscription
is established by providing a METASYS-SUBSCRIBE header with the GET
operation of a diagram.
See also:
To subscribe to a diagram use the Get diagram operation
and include a METASYS-SUBSCRIBE header. The value of this header should be the
stream id you received when you opened a stream.
Here are the types of events sent by the diagram subscription along with example
data payloads for each.
diagram.subscription.established - Indicates when a subscription has been
established for the diagram.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
"message": "Live value subscription successful"
}
diagram.subscription.cancelled - Indicates when a subscription has been
cancelled for the diagram.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "Live value subscription cancelled"
}
diagram.values.update - Indicates a change in value of blocks or ports
within the diagram. The first occurrence of this event will include all values
in the diagram. Subsequent occurrences will only include values that changed
from the previous occurrence.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
"items": [
["8", 2.0],
["9", 2.0, { "reliability": "reliabilityEnumSet.writeError" }]
]
}
Each entry in items is a tuple of 2 or 3 values:
id property of the diagram entity.null.The first diagram.values.update event payload for a new subscription of a
diagram will contain all current values of entities in the diagram. Subsequent
events will only contain values that changed from the previous event.
diagram.error - Indicates an error occurred during cancelling a
subscription.
{
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "Error while cancelling subscription"
}
diagram.heartbeat - Indicates that the logic service is alive.
"ping from logic service @2021-08-04T16:03:23.3771485Z"
diagram.update - Indicates a change in the structure of the diagram. This
event will cause the subscription to be cancelled.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "The diagram has been updated.. Please refresh. Current subscription will be cancelled automatically."
}
An instance of a control is really an instance of an object available at the
relative URL of /objects/{objectId}. As a control, the representation of the
object is more aligned with control logic in an abstracted manner rather than a
more primitive and more complex representation.
Retrieves the diagram of the specified control instance.
If the METASYS-SUBSCRIBE header is provided, then an event subscription
will be created which will include the events described in
Diagrams
| controlId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the control. |
| includeSchema | boolean Default: false Indicates whether the schema of the diagram should also be returned. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/controls/5a22812f-ec51-4c11-ab4a-fc986f94f008/diagram?includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Shows the results of a diagram with no blocks or connections.
{- "id": "5a22812f-ec51-4c11-ab4a-fc986f94f008",
- "name": "System1",
- "environment": {
- "engine": "lct",
- "engineVersion": "1.0",
- "maximums": {
- "inputs": {
- "allOf": [
- "input-float",
- "input-boolean",
- "input-enumeration"
], - "maximum": 24
}, - "outputs": {
- "allOf": [
- "output-float",
- "output-boolean",
- "output-enumeration"
], - "maximum": 24
}
}
}, - "item": {
- "blocks": [ ],
- "connections": [ ]
}
}Replaces the diagram of the specified control instance.
There are a variety of errors that are possible when attempting to update a diagram. Every known error that can be determined will be communicated in a response. The error response is hierarchical such that the top-most errors describe generalized issues while inner-most errors describe specific issues. Each error is intended to be self-descriptive with accompanying details.
api.diagram:error.saveFailed
The save failed. innerError or innerErrors will have more information
api.diagram:error.schemaFailure
The payload did not validate against the schema.
api.diagram:error.diagramSchemaFailure
The diagram did not validate against the schema.
api.diagram:error.invalidSchemaUrl
A block's schema URL is invalid or doesn't reference a known block type.
api.diagram:error.blockSchemaFailure
A block did not validate against its schema.
api.diagram:error.connectionSchemaFailure
A connection did not validate against its schema.
api.diagram:error.unboundReferences
The configured object reference for an Input Reference or Output Reference could not be resolved.
enum.core:statusEnumSet.writeAccessDeniedSecurity
The user is not authorized to modify the diagram.
api.diagram:error.unauthorizedExistingDiagram
The user is not authorized to modify the existing diagram.
api.diagram:error.unauthorizedRequestDiagram
The user is not authorized to control some references in the new diagram.
api.diagram:error.duplicateId
The same id is defined multiple times in the diagram.
api.diagram:error.circularLogic
An unsupported circular loop has been defined in the diagram.
api.diagram:error.ioAttributes
A general wrapper for any errors related to Input Attributes and Output Attributes.
api.diagram:error.ioThresholdExceeded
The diagram contains more than the maximum allowed inputs or outputs.
api.diagram:error.duplicateIOBlockName
The diagram contains duplicate Input Attribute and Output Attribute names.
api.diagram:error.duplicateIOAttribute
The diagram contains duplicate Input Attribute and Output Attribute identifiers.
api.diagram:error.connection
A general wrapper for any errors related to a connection.
api.diagram:error.portDoesNotExist
The port referenced by a connection's source or destination is not defined.
api.diagram:error.portsCannotBeFromSameBlock
A connection's source and destination cannot be from the same block.
api.diagram:error.delayConnectedToOutputTypeBlock
A Delay block should not be connected to an Output Reference or Output Attribute.
api.diagram:error.priorityNotSupported
A connection does not support priority when connected to anything other than Output Reference.
api.diagram:error.portDirectionInvalidForConnectionEndpoint
The source of a connection cannot be an input port of a block and the destination of a connection cannot be an output port of a block.
api.diagram:error.block
A general wrapper for any errors related to a block.
api.diagram:error.invalidEnum
An enumeration value is not valid.
api.diagram:error.duplicatePortInSubSystem
A System block cannot define a port as both being an input and an output.
api.diagram:error.portDoesNotExistInSubSystem
A System block exposes a port which is not defined.
api.diagram:error.inPortIsNotWritableInSubSystem
A System block exposes a input port which is not writable.
api.diagram:error.limitsCountMismatchInSequencer
A Sequencer block doesn't have the same number of make limit values as break limit values.
api.diagram:error.limitsDoesNotMatchOutputsInSequencer
A Sequencer block must have the same number of make & break limit values
as the number of outputs. If proactive is true, then the expected
count of limit values should be one less than the number of outputs.
api.diagram:error.limitsNotInAscendingOrderInSequencer
A Sequencer block must have make & break limit values in ascending order.
api.diagram:error.breakIsGreaterThanMakeInSequencer
A Sequencer block must have break limits which are less than their corresponding make limit of the same stage.
api.diagram:error.makeIsGreaterThanBreakInSequencer
A Sequencer block must have make limits which are less than the break limit of the previous stage.
api.diagram:error.duplicateModeSelectionInMux
A Multiplexor (MUX) block cannot use the same mode enumeration value multiple times.
| controlId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the control. |
The desired blocks and connections of the diagram. This is the same
structure as the item property from the GET /diagram response.
required | object (Diagram) A set of blocks and connections which make up an instance of programmable control logic. |
A diagram with no blocks or connections.
{- "item": {
- "blocks": [ ],
- "connections": [ ]
}
}Shows the response of a replace diagram request which had no item property.
{- "statusName": "api.diagram:error.saveFailed",
- "message": "Diagram save failed. Please see innerError(s) for more information.",
- "innerError": {
- "statusName": "api.diagram:error.schemaFailure",
- "message": "Schema validation failed for diagram. Please see innerError(s) for more information.",
- "innerError": {
- "statusName": "api.diagram:error.diagramSchemaFailure",
- "message": "Diagram instance failed schema validation. Please see details for more information.",
- "details": {
- "valid": false,
- "errors": [
- {
- "valid": false,
- "keywordLocation": "#/required",
- "instanceLocation": "#",
- "keyword": "required",
- "additionalInfo": {
- "missing": [
- "item"
]
}
}
]
}
}
}
}Deletes a subscription to a control resource.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/controls/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Retrieves a palette, which defines the available types of blocks available to diagramming.
| paletteId required | string Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21 The identifier of the palette. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
An LCT palette (this is only a partial example).
{- "id": "01443cbc-d65e-4666-85d5-484a3b1f4f21",
- "name": "Core LCT Palette",
- "items": [
- {
- "id": "tool",
- "name": "Tools",
- "description": "A free form block of text.",
- "type": "text.",
- "definitions": [
- {
- "title": "Text",
- "description": "The schema for a text block instance",
- "type": "object",
- "properties": {
- "id": {
- "type": "integer",
- "minimum": 1
}, - "schemaUrl": {
- "type": "string",
- "format": "uri",
}, - "location": {
- "type": "object",
- "properties": {
- "x": {
- "type": "number"
}, - "y": {
- "type": "number"
}
}, - "required": [
- "x",
- "y"
]
}, - "text": {
- "type": "string",
- "metasysType": "string",
- "pattern": "^[^:\\\"]*$",
- "default": "Untitled"
}, - "width": {
- "type": "number",
- "metasysType": "float",
- "default": 40,
- "minimum": 1,
- "maximum": 3.40282347e+38
}
}, - "required": [
- "id",
- "schemaUrl",
- "location",
- "text"
], - "additionalProperties": false,
- "views": [
- {
- "id": "viewNameEnumSet.configView",
- "title": "Configuration",
- "views": [
- {
- "id": "groupTypeEnumSet.basicGrpType",
- "title": "Basic",
- "views": [
- {
- "id": "viewGroupEnumSet.displayGrp",
- "title": "Display",
- "properties": [
- "text"
]
}
]
}
]
}
]
}
]
}
]
}Retrieves the schema for a specific block type.
| paletteId required | string Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21 The identifier of the palette. |
| blockDefinitionId required | string Examples:
The ID of the block definition to get the schema for. The ID is the last
portion of the |
curl --request GET \ --url https://metasys-server.example.com/api/v5/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21/text \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The Text Block definition on the LCT palette.
{- "title": "Text",
- "description": "The schema for a text block instance",
- "type": "object",
- "properties": {
- "id": {
- "type": "integer",
- "minimum": 1
}, - "schemaUrl": {
- "type": "string",
- "format": "uri",
}, - "location": {
- "type": "object",
- "properties": {
- "x": {
- "type": "number"
}, - "y": {
- "type": "number"
}
}, - "required": [
- "x",
- "y"
]
}, - "text": {
- "type": "string",
- "metasysType": "string",
- "pattern": "^[^:\\\"]*$",
- "default": "Untitled"
}, - "width": {
- "type": "number",
- "metasysType": "float",
- "default": 40,
- "minimum": 1,
- "maximum": 3.40282347e+38
}
}, - "required": [
- "id",
- "schemaUrl",
- "location",
- "text"
], - "additionalProperties": false,
- "views": [
- {
- "id": "viewNameEnumSet.configView",
- "title": "Configuration",
- "views": [
- {
- "id": "groupTypeEnumSet.basicGrpType",
- "title": "Basic",
- "views": [
- {
- "id": "viewGroupEnumSet.displayGrp",
- "title": "Display",
- "properties": [
- "text"
]
}
]
}
]
}
]
}Enumerations are an important data type used by Metasys®. A single enumeration is used to define a set of values a property can have and each value includes a localized string to describe itself.
| enumType | string Default: "all" Enum: "all" "twoState" "multiState" "custom" Examples:
The type of enumerations to return. |
| minNumberOfStates | integer Example: minNumberOfStates=4 Filter the result to include only those multi-state and custom enumerations with at least the specified |
| includePermissions | boolean Default: false Include effective permissions for the client with respect to enumerations. |
| Accept-Language | Array of strings Example: en-US, de-De The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used. |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/enumerations?enumType=all&minNumberOfStates=4&includePermissions=false' \ --header 'Accept-Language: en-US, de-De'
{- "items": {
- "customEnumSet30001": {
- "isMultiState": true,
- "isMutable": true,
- "name": "Speed",
- "numberOfStates": 3
}, - "customEnumSet30002": {
- "isTwoState": true,
- "isMutable": true,
- "name": "Rotation"
}
}
}Create a custom enumeration with members of your choice
New enumeration
required | object An enumeration |
{- "item": {
- "name": "Speed",
- "members": [
- "Slow",
- "Fast",
- "Very Fast"
]
}
}{- "item": {
- "name": "Speed",
- "members": {
- "customEnumSet30001.0": {
- "value": 0,
- "name": "Slow"
}, - "customEnumSet30001.1": {
- "value": 1,
- "name": "Fast"
}, - "customEnumSet30001.2": {
- "value": 2,
- "name": "Very Fast"
}
}
}
}Get an enumeration
| id required | string Examples:
The enumeration to retrieve. To see a list of all possible enumeration |
| includeSchema | boolean Include the schema of the enumeration. The schema will tell you which members of the enumeration (if any) are editable. |
| includePermissions | boolean Include the effective permissions the client has with respect to this enumeration. |
| Accept-Language | Array of strings Example: en-US, de-De The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used. |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/enumerations/writePriorityEnumSet?includeSchema=false&includePermissions=false' \ --header 'Accept-Language: en-US, de-De'
{- "item": {
- "name": "Absent Present",
- "members": {
- "absentpresentEnumSet.0": {
- "value": 0,
- "name": "Absent"
}, - "absentpresentEnumSet.1": {
- "value": 1,
- "name": "Present"
}, - "absentpresentEnumSet.2": {
- "value": 2,
- "name": "Hold"
}
}
}
}Can be used to modify the name of the enumeration and the values of any of the member strings. Cannot be used to add/remove members.
| id required | string Example: customEnumSet30001 The enumeration to edit. |
required | object |
{- "item": {
- "name": "Speeds",
- "members": {
- "customEnumSet30001.1": {
- "name": "Medium"
}, - "customEnumSet30001.2": {
- "name": "Fast"
}
}
}
}{- "item": {
- "name": "Speeds",
- "members": {
- "customEnumSet30001.0": {
- "value": 0,
- "name": "Slow"
}, - "customEnumSet30001.1": {
- "value": 1,
- "name": "Medium"
}, - "customEnumSet30001.2": {
- "value": 2,
- "name": "Fast"
}
}
}
}Replace an enumeration with a new definition. You can not replace a two-state enumeration with a multiple-state enumeration. Nor can you replace a multiple-state enumeration with a two-state enumeration.
| id required | string Example: customEnumSet30001 The enumeration to replace |
required | object An enumeration |
{- "item": {
- "name": "Speed",
- "members": [
- "Slow",
- "Fast",
- "Very Fast"
]
}
}{- "item": {
- "name": "Speed",
- "members": {
- "customEnumSet30001.0": {
- "value": 0,
- "name": "Slow"
}, - "customEnumSet30001.1": {
- "value": 1,
- "name": "Fast"
}, - "customEnumSet30001.2": {
- "value": 2,
- "name": "Very Fast"
}
}
}
}Delete an enumeration. Only custom enumerations may be deleted.
| id required | string Example: customEnumSet30001 The enumeration to delete. |
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/enumerations/customEnumSet30001 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This section describes the operations you can perform on equipment. Equipment is a broad term for anything that makes a building run, including boilers, chillers, air handling units, lights, meters, and security systems. Use equipment operations to get equipment instances and to list equipment points. Apply filters, sorting, and paging to further refine the results.
Retrieves the collection of equipment instances hosted by the specified network device or its children. A network device is considered to host an equipment if the equipment defines points that map to an attribute of any object contained on the network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves a collection of equipment instances.
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves the specified equipment instance.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A single equipment instance.
{- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}Retrieves the equipment served by the specified equipment instance.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "04d68394-3415-4813-b5ec-43d840deee38",
- "itemReference": "{hostname}:{deviceHostname}/equipment.VAV-1",
- "name": "VAV-1",
- "type": "VAV Boxes",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves the collection of equipment that serve the specified equipment instance.
| equipmentId required | string Example: 04d68394-3415-4813-b5ec-43d840deee38 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves the collection of points that are defined by the specified equipment instance. Each point contains a mapping to an attribute on an object.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "shortName" Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName" Example: sort=shortName The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/points?page=1&pageSize=100&sort=shortName' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment points
{- "total": 31,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLG-MAXFLOW",
- "label": "Cooling Max Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLG-MINFLOW",
- "label": "Cooling Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLG-O",
- "label": "Cooling Output",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGOCC-MINFLOW",
- "label": "Occ Cooling Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGOCC-SP",
- "label": "Cooling Occupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGUNOCC-MINFLOW",
- "label": "Unocc Cooling Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGUNOCC-SP",
- "label": "Cooling Unoccupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "DA-VP",
- "label": "Discharge Air Velocity Pressure",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "DPR-O",
- "label": "Supply Air Damper Output",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "EFFCLG-SP",
- "label": "Effective Cooling Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "EFFHTG-SP",
- "label": "Effective Heating Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "EFF-OCC",
- "label": "Effective Occupancy State",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTG-MINFLOW",
- "label": "Heating Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGOCC-MINFLOW",
- "label": "Occ Heating Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGOCC-SP",
- "label": "Heating Occupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGUNOCC-MINFLOW",
- "label": "Unocc Heating Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGUNOCC-SP",
- "label": "Heating Unoccupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "OCC-MODE",
- "label": "Occupancy Status Display",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "OCC-SCHEDULE",
- "label": "Occupancy Schedule",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SA-F",
- "label": "Supply Air Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SAFLOW-SP",
- "label": "Flow Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SA-T",
- "label": "Supply Air Temperature",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SYSTEM-MODE",
- "label": "System Mode",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "UNITEN-MODE",
- "label": "Unit Enable Mode",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "WC-ADJ",
- "label": "Warmer/Cooler Adjust",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "WC-C",
- "label": "WarmupCooldown",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-SP",
- "label": "Zone Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-T",
- "label": "Zone Temperature",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-TOCC",
- "label": "Zone Temporary Occupancy",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-TOCC",
- "label": "Zone Temporary Occupancy",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZNT-STATE",
- "label": "Zone Status",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}
],
}Retrieves the collection of equipment that serve the specified space.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Get accounts report
curl --request GET \ --url https://metasys-server.example.com/api/v5/health/reports/accounts \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "accountTypeCounts": {
- "active": {
- "count": 3,
- "users": [
- {
- "userName": "api-user",
- "fullName": "API User",
- "isAdmin": true
}, - {
- "userName": "MetasysSysAgent",
- "fullName": "Metasys System Agent",
- "isAdmin": true
}, - {
- "userName": "Operator",
- "fullName": "Metasys System Operator",
- "isAdmin": false
}
], - "severityLevel": 0
}, - "admin": {
- "count": 2,
- "users": [
- {
- "userName": "api-user",
- "fullName": "API User",
- "isAdmin": true
}, - {
- "userName": "MetasysSysAgent",
- "fullName": "Metasys System Agent",
- "isAdmin": true
}
], - "severityLevel": 0
}, - "disabled": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "dormant": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "locked": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "temporary": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "total": {
- "count": 3,
- "users": [
- {
- "userName": "api-user",
- "fullName": "API User",
- "isAdmin": true
}, - {
- "userName": "MetasysSysAgent",
- "fullName": "Metasys System Agent",
- "isAdmin": true
}, - {
- "userName": "Operator",
- "fullName": "Metasys System Operator",
- "isAdmin": false
}
], - "severityLevel": 0
}, - "basic": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "standard": {
- "count": 2,
- "users": [
- {
- "userName": "MetasysSysAgent",
- "fullName": "Metasys System Agent",
- "isAdmin": true
}, - {
- "userName": "Operator",
- "fullName": "Metasys System Operator",
- "isAdmin": false
}
], - "severityLevel": 0
}, - "tenant": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}
}, - "policyViolationCounts": {
- "dormantPeriod": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "neverDormant": {
- "count": 1,
- "users": [
- {
- "userName": "api-user",
- "fullName": "API User",
- "isAdmin": true
}
], - "severityLevel": 1
}, - "lockoutConfiguration": {
- "count": 2,
- "users": [
- {
- "userName": "MetasysSysAgent",
- "fullName": "Metasys System Agent",
- "isAdmin": true
}, - {
- "userName": "Operator",
- "fullName": "Metasys System Operator",
- "isAdmin": false
}
], - "severityLevel": 1
}, - "neverLockout": {
- "count": 1,
- "users": [
- {
- "userName": "api-user",
- "fullName": "API User",
- "isAdmin": true
}
], - "severityLevel": 2
}, - "noPasswordHistory": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "passwordExpiresPeriod": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "passwordNeverExpires": {
- "count": 1,
- "users": [
- {
- "userName": "api-user",
- "fullName": "API User",
- "isAdmin": true
}
], - "severityLevel": 2
}, - "rememberPasswordsPeriod": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}, - "neverTerminate": {
- "count": 1,
- "users": [
- {
- "userName": "api-user",
- "fullName": "API User",
- "isAdmin": true
}
], - "severityLevel": 2
}, - "terminateMinutes": {
- "count": 0,
- "users": [ ],
- "severityLevel": 0
}
}
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Get devices report
curl --request GET \ --url https://metasys-server.example.com/api/v5/health/reports/devices \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "pre52": {
- "count": 0,
- "users": null,
- "severityLevel": 0
}, - "post52Pre81": {
- "count": 0,
- "users": null,
- "severityLevel": 0
}, - "post81": {
- "count": 2,
- "users": null,
- "severityLevel": 0
}, - "expiringCerts": {
- "count": 0,
- "users": null,
- "severityLevel": 0
}, - "expiredCerts": {
- "count": 0,
- "users": null,
- "severityLevel": 0
}
}This section describes the operations you can perform on network devices. Network devices are physical devices such as coordinators and routers that are required for communication between hardware on a computer network. Use network device operations to get, list, and delete network devices. Apply filters, sorting, and paging to further refine the results.
Retrieves a collection of network devices.
| objectType | string Example: objectType=bacnetIntegrationClass metasysType: enum metasysEnum: objectTypeEnumSet The type of network device to return. The The acceptable values for this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
| classification | Array of strings Items Enum: "device" "integration" "server" "controller" Examples:
The classification to filter devices on. One or more values are supported. The |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/networkDevices?objectType=bacnetIntegrationClass&page=1&pageSize=100&sort=name&classification=device&classification=server&classification=controller' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}, - "objectTypeVersion": "37.0",
- "productVersion": "11.7"
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
], - "canModify": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
]
}
}Retrieves the specified network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A single network device.
{- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}, - "objectTypeVersion": "37.0",
- "productVersion": "11.7"
}Deletes an engine or a server which is a child device of the site director. Cannot be used to delete controllers, integrations, or the site director.
Note: The device must be offline for the operation to succeed.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Retrieves the collection of network devices that are children of the specified network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/networkDevices?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "88cc68b1-ddaf-48c9-b15e-6ea112be848f",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Engine",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/88cc68b1-ddaf-48c9-b15e-6ea112be848f/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/88cc68b1-ddaf-48c9-b15e-6ea112be848f/trendedAttributes",
- "ipAddress": "192.168.0.2",
- "certificateExpirationDate": null,
- "pairing": {
- "supported": true,
- "paired": false
}, - "objectTypeVersion": "37.0",
- "productVersion": "11.7"
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "88cc68b1-ddaf-48c9-b15e-6ea112be848f"
], - "canModify": [
- "88cc68b1-ddaf-48c9-b15e-6ea112be848f"
]
}
}Allows for batching multiple requests to many network devices.
The following operations relative to a network device are supported:
| Relative Path | GET |
POST |
PUT |
PATCH |
DELETE |
|---|---|---|---|---|---|
{networkDeviceId}/certificates/bacnet |
✔ | ✔ | ❌ | ❌ | ✔ |
{networkDeviceId}/signingRequests/bacnet |
✔ | ✔ | ✔ | ❌ | ✔ |
This batch operation supports up to 1000 requests at a time.
The certificate signing request body in responses is base64 encoded PEM
content, which is different from the non-batch PEM response.
The schema of the request body is inconsistent with other batch paths. See GIV-108568.
A collection of individual requests relative to the networkDevices path. All requests will use the same HTTP method and should be for the same resource type relative to the network device.
object or string An optional shared body for all requests. This will be ignored for any individual request which defines its own | |
required | Array of objects non-empty An array of individual requests. |
Create certificate signing requests for multiple devices with the same parameters.
{- "body": {
- "city": "Milwaukee",
- "country": "US",
- "emailAddress": "noreply@jci.com",
- "orgName": "Johnson Controls",
- "orgUnitName": "BAS",
- "stateProvince": "WI"
}, - "requests": [
- {
- "id": "1",
- "method": "POST",
}, - {
- "id": "2",
- "method": "POST",
}
]
}Create certificate signing requests for multiple devices with the same parameters.
{- "responses": [
- {
- "id": "1",
- "status": 201,
- "headers": {
- "eTag": "2w6Fdcn6PJ9jrCl5Mo5fS5Vq6oVMjZc+ejN5QlFFdy8=",
- "last-modified": "Tue, 17 Aug 2021 18:36:05 GMT"
}, - "body": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQlRUQ0I5QUlCQWpDQmtURUxNQWtHQTFVRUJoTUNWVk14Q3pBSkJnTlZCQWdNQWxkSk1SSXdFQVlEVlFRSApEQWxOYVd4M1lYVnJaV1V4R1RBWEJnTlZCQW9NRUVwdmFHNXpiMjRnUTI5dWRISnZiSE14RERBS0JnTlZCQXNNCkEwSkJVekVZTUJZR0ExVUVBd3dQVFVGRE1ESTBNakJFTWprd05qVXlNUjR3SEFZSktvWklodmNOQVFrQkZnOXUKYjNKbGNHeDVRR3BqYVM1amIyMHdXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBUTN4TUtOejVRMwozTVJ2YUpOaUIraEYza21UODljRE5qK01OUndac2FOSTBtNktWTkhveEZ5N25sTEVwUFlURjlQdmR6VVZrYjZiCmR4VWppalp2aWVEY29BQXdDZ1lJS29aSXpqMEVBd0lEU0FBd1JRSWdERVNSblFjN1NVcWtSRVBxdGxaSzhRWE8KY1Ivd2JpbzB0OEdmY3RLZEwzMENJUURmS3IrcHp0S0VYWUtEZ0J6UHl4SVZoa1pkb0YrTnk0aCtVdi9XUWNtRwpJZz09Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo="
}, - {
- "id": "2",
- "status": 201,
- "headers": {
- "eTag": "Ugvge9WTeytxKZsUEQzsuQPX4gXvDpysa/m0NtMLnRE=",
- "last-modified": "Tue, 17 Aug 2021 18:36:05 GMT"
}, - "body": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQlRqQ0I5QUlCQWpDQmtURUxNQWtHQTFVRUJoTUNWVk14Q3pBSkJnTlZCQWdNQWxkSk1SSXdFQVlEVlFRSApEQWxOYVd4M1lYVnJaV1V4R1RBWEJnTlZCQW9NRUVwdmFHNXpiMjRnUTI5dWRISnZiSE14RERBS0JnTlZCQXNNCkEwSkJVekVZTUJZR0ExVUVBd3dQVFVGRE1ESTBNamN3TXpWQlF6WkVNUjR3SEFZSktvWklodmNOQVFrQkZnOXUKYjNKbGNHeDVRR3BqYVM1amIyMHdXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBUTdiWExaNDZQeQpSaTc5Tlpka2REWko3SitFUnRZMVRqT0QrWDYra1VrYlQ2TElBRnZncjJxL25GOEo1eHRsSXM2bGJPOXY3T29vCklFRmhKN0tMa2NaR29BQXdDZ1lJS29aSXpqMEVBd0lEU1FBd1JnSWhBT0VDbjJaNDhnZzNFRmJtdXpMU0NXWkQKNEUyaEw0d1ZhRmpZMkNmdTdGdWFBaUVBOGphUVc3Z0ZxZjVWNS83WkFiL2RVQnZScXBWQVFYNERHTlBkNnEwbQp1d0U9Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo="
}
]
}Retrieves the collection of network devices that host the specified equipment instance, along with the parents of those network devices. A network device hosts an equipment when the equipment defines points that map to an attribute of any object contained on the network device.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}, - "objectTypeVersion": "37.0",
- "productVersion": "11.7"
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
], - "canModify": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
]
}
}Retrieves the collection of network devices that serve the specified space. A space serves a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}, - "objectTypeVersion": "37.0",
- "productVersion": "11.7"
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
], - "canModify": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
]
}
}Retrieves a list of objects for the well known alarm query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/alarm?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are in alarm for the device. The object id needs to be a supervisory device.
{- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "name": "AV1",
- "description": "AV1",
- "objectType": "objectTypeEnumSet.avClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osLowAlarm",
- "value": {
- "item": 70.1965561,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}, - "unitsSource": "attributeEnumSet.units",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "displayPrecisionSource": "attributeEnumSet.displayPrecision"
}
}
}, - {
- "id": "187d032d-6156-5d9f-bfe8-c2a14d5c22df",
- "itemReference": "{hostname}:{deviceHostname}/SF-S",
- "name": "Supply Fan Status",
- "description": "Supply Fan Status",
- "objectType": "objectTypeEnumSet.mvClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osAlarm",
- "value": {
- "item": "offonEnumSet.0",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "enumSetSource": "attributeEnumSet.statesText",
}
}
}
]
}Retrieves a list of objects for the well known disabled query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/disabled?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are disabled.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/ZN-T.Trend1",
- "name": "Trend - Present Value",
- "description": null,
- "objectType": "objectTypeEnumSet.trendLogClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osDisabled"
}
]
}Retrieves a list of objects for the well known offline query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/offline?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are offline.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOffline"
}
]
}Retrieves a list of objects for the well known operator override query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/operatorOverride?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are in operator override.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.RA-T",
- "name": "RA-T",
- "description": "RA-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOperatorOverride",
- "value": {
- "item": 70.1965561,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}, - "unitsSource": "attributeEnumSet.units",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "displayPrecisionEnumSet": "attributeEnumSet.displayPrecision"
}
}
}
]
}Retrieves a list of objects for the well known out of service query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/outOfService?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are out of service.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOutOfService"
}
]
}Retrieves a list of objects for the well known supervisory override query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/supervisoryOverride?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are in supervisory override.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOperatorOverride",
- "value": {
- "item": 70.1965561,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}, - "unitsSource": "attributeEnumSet.units",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "displayPrecisionEnumSet": "attributeEnumSet.displayPrecision"
}
}
}
]
}Retrieves a list of objects for the well known trouble query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/trouble?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that have a trouble status.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE"
}
]
}An object tree is a hierarchical structure of objects. Metasys exposes trees in its user interfaces (and this API) to provide a means of discovery and navigation. The built-in tree is the "all items" tree which is also called the network tree. Users can also create their own custom hierarchies of trees. These are called interchangeably user defined trees or user views.
This section of the API provides operations to discover and retrieve the various object trees defined in the system.
Returns a list of all the navigation trees for objects. This includes the "all-items" tree as well as the user defined trees (user views). The list will contain all of the object trees on the system but the effectivePermissions.canRead property in the response payload will list only those trees that the user can read.
curl --request GET \ --url https://metasys-server.example.com/api/v5/objects/trees \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- {
- "default": true,
- "treeType": "hardware",
- "tree": {
- "items": [
- {
- "id": "8e16a75e-20e8-55bd-ac11-926c1122d69c",
- "itemReference": "{hostname}:{hostname}/$site",
- "name": "Site",
- "objectType": "objectTypeEnumSet.siteClass",
- "hasChildrenMatchingQuery": true
}
]
}
}, - {
- "treeType": "userDefined",
- "itemReference": "{hostname}:{hostname}/$site.UserTrees.Building1",
- "name": "Building 1"
}, - {
- "treeType": "userDefined",
- "itemReference": "{hostname}:{hostname}/$site.UserTrees.Building2",
- "name": "Building2"
}
], - "effectivePermissions": {
}
}This operation fetches the specified tree.
This operation differs from
Get an object in that it actually
returns the tree, whereas Get an object returns the object
representation of the user view. The object representation contains metadata
about the user view (for example, its name, objectCategory and
itemReference).
Note: The response to this operation does not include modification
constraints. If you wish to see modification constraints for the objects
call GET /trees/{treeId}/objects or
GET /trees/{treeId}/objects/{objectId}/objects
See also:
| treeId required | string Example: c0d8ebe7-d246-5bc3-a16c-c1aa19589c45 The unique object identifier of the tree to retrieve. To discover the set of
available |
| includePermissions | boolean Default: false Example: includePermissions=true Include effective permissions of the current user with respect to the objects in this tree. |
| includeConditions | boolean Default: false Example: includeConditions=true Include a condition section in the payload that lists any objects that have been deleted. (In the future this section could be used to indicate any other useful condition flags.) |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/trees/c0d8ebe7-d246-5bc3-a16c-c1aa19589c45?includePermissions=true&includeConditions=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- {
- "itemReference": "{hostname}:{hostname}/$site.UserTrees.User View",
- "id": "c0d8ebe7-d246-5bc3-a16c-c1aa19589c45",
- "label": "Building 1",
- "objectType": "objectTypeEnumSet.navTreeClass",
- "classification": "navList",
- "version": "1.0",
- "items": [
- {
- "itemReference": "{hostname}:{hostname}",
- "id": "c05d5d30-ebf0-5533-8e67-f74bb728bf18",
- "label": "Site Director",
- "objectType": "objectTypeEnumSet.adsClass",
- "classification": "server",
- "version": "37.0",
}, - {
- "itemReference": "{hostname}:{deviceHostname}",
- "id": "af69c7ad-d7d6-58bd-81a8-f3a80a047148",
- "label": "NAE1",
- "objectType": "objectTypeEnumSet.nae55SmarcClass",
- "classification": "device",
- "version": "7.0",
}, - {
- "itemReference": "User View.Programming",
- "id": "6e5eea13-a1d8-449b-92f9-00e8e5812025",
- "label": "Programming",
- "objectType": "objectTypeEnumSet.userVewFolderClass",
- "classification": "folder",
- "version": "1.0",
- "items": [
- {
- "itemReference": "{hostname}:{deviceHostname}/Test Folder.AV1",
- "id": "d0024ef6-c0c2-5726-a228-64609d860f9e",
- "label": "AV1",
- "objectType": "objectTypeEnumSet.avClass",
- "classification": "object",
- "version": "1.0",
}, - {
- "itemReference": "{hostname}:{deviceHostname}/Test Folder.AV2",
- "id": "6acd91ff-6ee5-50e1-9a6d-7363f3b41616",
- "label": "AV2",
- "objectType": "objectTypeEnumSet.avClass",
- "classification": "object",
- "version": "1.0",
}, - {
- "itemReference": "{hostname}:{deviceHostname}/Test Folder.AV3",
- "id": "7bbc1d1b-dcfd-53e5-bbbd-a73dac0f287a",
- "label": "AV3",
- "objectType": "objectTypeEnumSet.avClass",
- "classification": "object",
- "version": "1.0",
}
],
}
],
}
], - "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "d0024ef6-c0c2-5726-a228-64609d860f9e",
- "6acd91ff-6ee5-50e1-9a6d-7363f3b41616",
- "7bbc1d1b-dcfd-53e5-bbbd-a73dac0f287a"
], - "canModify": [
- "d0024ef6-c0c2-5726-a228-64609d860f9e",
- "6acd91ff-6ee5-50e1-9a6d-7363f3b41616",
- "7bbc1d1b-dcfd-53e5-bbbd-a73dac0f287a"
]
}
}This section describes the operations you can perform on objects. Objects are self-contained functional items in the Metasys system, for a full definition refer to the Metasys System Glossary. Use objects operations to list, create, edit, and delete objects. Apply filters, sorting, and paging to further refine the results. Some operations accept subscriptions, see Change of Value Subscriptions.
(INTERNAL) Some operations have limitations, see Operation Restrictions.
Subscribe for change of value (COV) events to receive updates when attribute values change. Currently, subscriptions are available for Get attribute value operations (individual and batch).
To subscribe for COV events, complete the following steps:
METASYS-SUBSCRIBE header
with the stream ID:Note: Any filters added to the original GET operation also apply to the event
subscription.
To unsubscribe from a COV event, complete the following steps:
METASYS-SUBSCRIPTION-LOCATION from the subscribe operation
response.METASYS-SUBSCRIPTION-LOCATION.See also:
COV Events : There are three event types sent by the COV subscription: heartbeat, update, and notification.
object.values.heartbeat - A heartbeat event is sent to show that the
subscription is still alive. A heartbeat is a JSON string with the current UTC
date time in ISO 8601 format and is sent every 30 seconds.
object.values.update - The client receives an update event when an attribute
value changes. This payload is similar in structure as the payload returned by
Get attribute value, but also includes id and itemReference of the
object to provide context for the attribute in question. The overall schema
for this payload is identical to the Get an object schema (except this
payload has no effectivePermissions property). The payload excludes the
schema for the attribute by default, but it can be optionally included by
using the includeSchema flag on the initial subscription request.
| subscriptionIds required | Array of strings <uuid> [ items <uuid > ] Subscription IDs that the update applies to |
required | object New value information for the subscribed attributes with additional identifying information for the object the update applies to. |
object (condition) This property contains condition flags (if any are set) for the properties of
| |
| schema | object A JSON schema that describes the properties of the |
{- "subscriptionIds": [
- "c9fcb046-4199-4f1c-a3e8-7841be1a3c30"
], - "item": {
- "presentValue": 76.5,
- "id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
- "itemReference": "{hostname}:{deviceHostname}/AV1"
}, - "condition": {
- "presentValue": {
- "reliability": "reliabilityEnumSet.reliable",
- "priority": "writePriorityEnumSet.priorityDefault"
}
}
}object.values.notification - A notification event is sent when a value has
changed but the value is not included in the payload. This happens for some
values that are not simple scalar values. You can use this event as a trigger
to reread the attribute. In the example, even though the payload does not
include the current value, you know which object this is for (based on id
and itemReference), and you know it is the overrideExpirationTime
attribute based on the attribute property.| subscriptionIds required | Array of strings <uuid> [ items <uuid > ] Subscription IDs that the notification applies to |
required | object Identifying information for the object the notification applies to which
a client can use to read the new value of the |
| attribute required | string metasysType: enum metasysEnum: attributeEnumSet The attribute the notification applies to. The values for this property come from the See also:
|
object (condition) This property contains condition flags (if any are set) for the properties of
|
{- "subscriptionIds": [
- "c9fcb046-4199-4f1c-a3e8-7841be1a3c30"
], - "item": {
- "id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
- "itemReference": "{hostname}:{deviceHostname}/AV1"
}, - "condition": {
- "overrideExpirationTime": {
- "reliability": "reliabilityEnumSet.reliable",
- "priority": "writePriorityEnumSet.priorityNone"
}
}, - "attribute": "attributeEnumSet.overrideExpirationTime"
}(PRIVATE) Ordering Events : There is one event types sent by the asynchronous ordering operation: update.
objects.ordering.update - The client receives an update event when an object
order changes. The data payload within the event includes the resulting
ordering. If the resulting ordering matches the requested ordering then the
payload will include a status property with the value statusEnumSet.ok,
otherwise the status will indicate an error:
statusEnumSet.operationCompletionError - There was an error updating the
ordering.statusEnumSet.deviceOffline - The update could not happen because the
device was offline.| self required | string The relative path to the new ordering for the child objects under
|
| subTreeUrl required | string The relative path to the child objects under |
| parentId required | string Parent ID that the update applies to |
| status required | object status can be any of statusEnumSet.ok, statusEnumSet.deviceOffline or statusEnumSet.OperationCompletionError |
| subscriptionIds required | Array of strings <uuid> [ items <uuid > ] Subscription IDs that the update applies to |
{- "self": "objects/f576ecbe-6ee2-5da5-a9b5-a89841b05cdc/objects/ordering",
- "subTreeUrl": "objects/f576ecbe-6ee2-5da5-a9b5-a89841b05cdc/objects",
- "parentId": "f576ecbe-6ee2-5da5-a9b5-a89841b05cdc",
- "status": "statusEnumSet.ok",
- "subscriptionIds": [
- "f06db843-920c-41c9-ac42-8dfd021a9b99"
]
}This section contains private notes about private asynchronous operations.
The following operations support asynchronous operations
None at this time.
To call an operation asynchronously it must accept the METASYS-CALL-ASYNC
header. Then follow these steps.
METASYS-CALL-ASYNC header with the
stream ID.To cancel a running asynchronous operation, complete the following steps:
Take note of the value of the METASYS-SUBSCRIPTION-LOCATION header included
in the response to the asynchronous operation request. (This location
represents a temporary subscription resource that is created for streaming
the results of the operation.)
Delete the subscription resource. For example
DELETE /objects/streams/{streamId}/subscriptions/{subscriptionsId}
See also:
There are restrictions on certain operations that are not otherwise communicated by the API. These are documented in the following requirements and restrict the creation of certain objects and the writing of certain attributes.
| Object Type | Forbidden Create | Forbidden Attribute Writes |
|---|---|---|
| Interlock | [G4R-4055][] | [G4R-4054][] - actionTbl1, actionTbl2, commandsPriority, source |
| MCO | [G4R-4057][] | [G4R-4056][] - actionTbl1, commandsPriority |
| DLLR | n/a | [G4R-4053][] - loadList |
| System | n/a | [G4R-4060][] - attributeInfo, fileName, logicSequence |
The attributes of the System object should be marked readOnly in the schema
and a CR (G4CR-8324) is written up for that. The other restrictions are
intended to be removed in a future release.
Returns the root object of the tree and, optionally, its children. The root
object is the site object. The default response is a tree representation.
Set flatten=true to flatten the tree into a list representation. The
number of levels returned depends on the value of the depth parameter. To
get just the root of the tree use a depth of 0. Values of depth greater
than 1 are not allowed on this endpoint.
| depth | integer [ 0 .. 1 ] Default: 1 Example: depth=1 The depth of the tree to return. The provided value is ignored if |
| flatten | boolean Default: false A value of |
| includeExtensions | boolean Default: false A value of This parameter is ignored if |
| pathTo | string Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a This parameter causes the response to contain the object specified by this parameter, the root object, and the objects in between. If this parameter is specified, then |
| includeInternal | boolean Default: false visibility: internal (INTERNAL) A value of |
| includeEffectivePermissions | boolean Default: false Example: includeEffectivePermissions=true Include the |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&includeInternal=false&includeEffectivePermissions=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The objects are returned in a tree structure. Child objects are nested under their parents.
{- "items": [
- {
- "parentUrl": null,
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site",
- "hasChildrenMatchingQuery": true,
- "name": "Site",
- "label": "{hostname}",
- "id": "767d8af0-163f-552c-ba37-a884466075f9",
- "objectType": "objectTypeEnumSet.siteClass",
- "objectTypeVersion": "1.1",
- "classification": "site",
- "items": [
- {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/851bf2f5-1043-5418-873a-182f0daa047f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.UserTrees",
- "hasChildrenMatchingQuery": false,
- "name": "User Views",
- "label": "UserTrees",
- "id": "851bf2f5-1043-5418-873a-182f0daa047f",
- "objectType": "objectTypeEnumSet.containerClass",
- "objectTypeVersion": "1.0",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/727072c8-bc67-5f38-8623-485a9d73af4f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.SummaryDefs",
- "hasChildrenMatchingQuery": false,
- "name": "Summary Definitions",
- "label": "SummaryDefs",
- "id": "727072c8-bc67-5f38-8623-485a9d73af4f",
- "objectType": "objectTypeEnumSet.containerClass",
- "objectTypeVersion": "1.0",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/8db194bc-68ee-599f-952e-983a7b86c456/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}",
- "hasChildrenMatchingQuery": true,
- "name": "{hostname}",
- "label": "{hostname}",
- "id": "8db194bc-68ee-599f-952e-983a7b86c456",
- "objectType": "objectTypeEnumSet.oasClass",
- "objectTypeVersion": "26.0",
- "classification": "server",
- "items": [ ]
}
]
}
], - "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "767d8af0-163f-552c-ba37-a884466075f9",
- "727072c8-bc67-5f38-8623-485a9d73af4f"
], - "canModify": [
- "767d8af0-163f-552c-ba37-a884466075f9",
- "727072c8-bc67-5f38-8623-485a9d73af4f"
]
}
}Creates a new object. Several things are needed to successfully create an object. You must know
Find the complete list of object types with the operation
GET /schemas/enums/objectTypeEnumSet. To determine the specific set of
objects that can be created in a location use List supported child types
(GET /objects/{objectId}/supportedChildTypes). To discover what object
properties can be set and which are required when creating an object use
Get a schema for an object type (GET /schemas/objectTypes/{objectType})
See also:
objectTypeEnumSet enumeration.| parentId required | string The ID of the parent object. The new object will be created under this object. |
| localUniqueIdentifier required | string <= 32 characters ^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$ A string that is locally unique within the context of the parent object
for identifying the new object. This string will be the last component of
the The value must not contain any control characters or any of the following
characters: |
| objectType required | string metasysType: enum metasysEnum: objectTypeEnumSet The type of object to create. The values for this property come from the See also:
|
| item | object The This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time. |
This request body creates a new object of type objectTypeEnumSet.avClass under a folder with an identifier of 82b6f2d5-6fed-5074-b611-94dd40028312 with a locally unique identifier of ZN-3-SETPT. The properties on the new object are name, description, objectCategory, minPresValue and maxPresValue.
{- "parentId": "82b6f2d5-6fed-5074-b611-94dd40028312",
- "localUniqueIdentifier": "ZN-3-SETPT",
- "objectType": "objectTypeEnumSet.avClass",
- "item": {
- "name": "Zone 3 Setpoint",
- "description": "Zone 3 Temperature Setpoint",
- "objectCategory": "objectCategoryEnumSet.hvacCategory",
- "minPresValue": 55,
- "maxPresValue": 95
}
}Returns the specified object and optionally one or more levels of the tree
under the object. The default response is a tree representation. Set
flatten=true to flatten the tree into a list representation.
| objectId required | string Example: 767d8af0-163f-552c-ba37-a884466075f9 Specifies the root of the subtree to return for this request. The |
| depth | integer >= -1 Default: 1 Example: depth=1 The depth of the tree to return. For typical usage, a value or 1 or 2 is
recommended. Use The provided value is ignored if |
| flatten | boolean Default: false A value of |
| includeExtensions | boolean Default: false A value of This parameter is ignored if |
| pathTo | string Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a This parameter filters the response down to just containing the object
specified by this parameter, the object specified by If this parameter is specified, then |
| objectType | string Examples:
metasysType: enum metasysEnum: objectTypeEnumSet Type of objects to include in the response. This parameter may be
repeated. To search for all AV and AI objects one would specify
The use of this parameter overrides It is an error to specify this parameter if The response will include the specified object, the objects that match
the The acceptable values for this parameter come from the See also:
|
| classification | string Enum: "object" "device" "integration" "controller" "point" "site" "navList" "extension" "folder" "reference" "server" "archive" Examples:
Filter objects to those with the specific classification. The use of this parameter overrides |
| includeInternal | boolean Default: false visibility: internal (INTERNAL) A value of |
| includeEffectivePermissions | boolean Default: false Example: includeEffectivePermissions=true Include the |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&objectType=objectTypeEnumSet.avClass&classification=object&includeInternal=false&includeEffectivePermissions=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The objects are returned in a tree structure. Child objects are nested under their parents.
{- "items": [
- {
- "parentUrl": null,
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site",
- "hasChildrenMatchingQuery": true,
- "name": "Site",
- "label": "{hostname}",
- "id": "767d8af0-163f-552c-ba37-a884466075f9",
- "objectType": "objectTypeEnumSet.siteClass",
- "objectTypeVersion": "1.1",
- "classification": "site",
- "items": [
- {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/851bf2f5-1043-5418-873a-182f0daa047f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.UserTrees",
- "hasChildrenMatchingQuery": false,
- "name": "User Views",
- "label": "UserTrees",
- "id": "851bf2f5-1043-5418-873a-182f0daa047f",
- "objectType": "objectTypeEnumSet.containerClass",
- "objectTypeVersion": "1.0",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/727072c8-bc67-5f38-8623-485a9d73af4f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.SummaryDefs",
- "hasChildrenMatchingQuery": false,
- "name": "Summary Definitions",
- "label": "SummaryDefs",
- "id": "727072c8-bc67-5f38-8623-485a9d73af4f",
- "objectType": "objectTypeEnumSet.containerClass",
- "objectTypeVersion": "1.0",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/8db194bc-68ee-599f-952e-983a7b86c456/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}",
- "hasChildrenMatchingQuery": true,
- "name": "{hostname}",
- "label": "{hostname}",
- "id": "8db194bc-68ee-599f-952e-983a7b86c456",
- "objectType": "objectTypeEnumSet.oasClass",
- "objectTypeVersion": "26.0",
- "classification": "server",
- "items": [ ]
}
]
}
], - "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "767d8af0-163f-552c-ba37-a884466075f9",
- "727072c8-bc67-5f38-8623-485a9d73af4f"
], - "canModify": [
- "767d8af0-163f-552c-ba37-a884466075f9",
- "727072c8-bc67-5f38-8623-485a9d73af4f"
]
}
}(NOT IMPLEMENTED) This is a design for an operation not yet implemented.
This endpoint changes the ordering of objects under a specified object.
This is an asynchronous operation which must be invoked with a valid
METASYS-CALL-ASYNC header (obtained by using the Get a stream
operation). If the request was valid, then when the operation completes an
objects.ordering.update event will be sent over the stream.
The data payload within the event includes the resulting ordering. If the
resulting ordering matches the requested ordering then the payload will
include a status property with the value statusEnumSet.ok, otherwise the
status will indicate an error:
statusEnumSet.operationCompletionError - There was an error updating the
ordering.statusEnumSet.deviceOffline - The update could not happen because the
device was offline.{
"self": "https://{hostname}/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects/ordering",
"subTreeUrl": "https://{hostname}/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects",
"parentId": "767d8af0-163f-552c-ba37-a884466075f9",
"status": "statusEnumSet.ok",
"subscriptionIds": ["538f00be-5788-4f68-a60e-45a14356c7ef"]
}
The subTreeUrl is the link to retrieve the result items.
Implementation details: If one or more object writes fail resulting in an ordering that does not match the requested ordering, then the status shall be
statusEnumSet.operationCompletionError. If one or more writes fail but the resulting ordering does match the requested ordering the status should bestatusEnumSet.ok. How might this happen? Assume I have the ordering[a, b, c, d]and I request to change it to[a, b, d, c]. I assume we attempt to write each object. Now if the writes toaandbfail, presumably that's fine since their values aren't changing. Note: Since this seems extremely unlikely (the only scenario we are aware where this would fail is when the device is offline) I'm okay with skipping the check in first implementation.
See also:
| objectId required | string Example: 767d8af0-163f-552c-ba37-a884466075f9 Specifies a parent object. |
| METASYS-CALL-ASYNC | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b visibility: private (PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response. See also: |
| items required | Array of strings An array of object identifiers. Each entry is an identifier of one of the child objects. The order of the identifiers in the array shall indicate the new ordering of the child objects. It is acceptable to send an array of identifiers that is a subset of all of the child object identifiers. In that case, the specified identifiers shall be ordered first. The identifiers that are not included in the request will maintain their relative order with respect to each other but shall come after all of the specified identifiers. For example, if the current ordering is |
{- "items": [
- "597b3cec-e452-5032-92fb-bcf837a65250",
- "7ca7fddf-0d54-53a0-b94c-f9a2a5f38e0b",
- "dcb93e5b-4395-53f2-aa8b-8f95dcc757f8",
- "2312c7e2-332f-55b1-a700-cf292fb5d815"
]
}Use Lookup object identifier instead.
Finds the object identifier (the id property of an object) for the object
with the specified fully qualified reference (fqr).
| fqr required | string Examples:
format: fully-qualified-reference The fully qualified reference of an object. It refers to an object's
Fully qualified references use characters that must be escaped when used as
query parameters. Most HTTP libraries do this for you automatically. However, if
you are using (PRIVATE) This parameter is actually optional. The |
| partialReference | string Examples:
visibility: private (PRIVATE) A partial reference of an object. A partial reference differs from a fully qualified reference in that the site portion of the fully qualified reference is omitted. Like a fully qualified reference, a partial reference may use characters
that must be escaped when used as a query parameter. (See the example in
the description of the This parameter cannot be specified if |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objectIdentifiers?fqr=adx%3Aadx&partialReference=adx' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).
| fqr required | string Examples:
format: fully-qualified-reference The fully qualified reference of an object. It refers to an object's
Fully qualified references use characters that must be escaped when used as
query parameters. Most HTTP libraries do this for you automatically. However, if
you are using (PRIVATE) This parameter is actually optional. The |
| partialReference | string Examples:
visibility: private (PRIVATE) A partial reference of an object. A partial reference differs from a fully qualified reference in that the site portion of the fully qualified reference is omitted. Like a fully qualified reference, a partial reference may use characters
that must be escaped when used as a query parameter. (See the example in
the description of the This parameter cannot be specified if |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/identifiers?fqr=adx%3Aadx&partialReference=adx' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"Objects support one or more views. By default, this operation gets the
default view of an object. For many objects this is the Focus View
(identifier viewNameEnumSet.focusView). To see the list of views an object
supports see List Views (/objects/{objectId}/views). To get a different
view of an object specify a value for the viewId parameter.
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| viewId | string Examples:
metasysEnum: viewNameEnumSet The view to retrieve. This parameter is optional and if it is not specified the default view
for the object will be returned. For many objects this is the Focus view
( The acceptable values for this parameter come from the See also:
|
| includeSchema | boolean Every object can have a unique schema. Set this parameter to |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb?viewId=viewNameEnumSet.focusView&includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This is an example of an AV object without a schema. Notice that the
presentValue is 105 but the maxPresValue is set to 100. This results
in the presentValue attribute going unreliable. This can be seen in the
condition object where presentValue has a reliability value of
reliabilityEnumSet.unreliableHigh. We can also see that the current
priority for presentValue is set to
writePriorityEnumSet.priorityCriticalEquipment.
{- "objectType": "objectTypeEnumSet.avClass",
- "networkDeviceUrl": "https://{hostname}/api/v5/networkDevices/8f2c6bb1-6bfd-5643-b581-299c1fec6b1b",
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/ce820989-5617-50bd-90ea-2fd95d1402ba/trendedAttributes",
- "item": {
- "name": "AV1",
- "description": null,
- "bacnetObjectType": "objectTypeEnumSet.bacAvClass",
- "objectCategory": "objectCategoryEnumSet.generalCategory",
- "outOfService": false,
- "reliability": "reliabilityEnumSet.unreliableHigh",
- "currentCommandPriority": 5,
- "alarmState": "objectStatusEnumSet.osNormal",
- "overrideExpirationTime": {
- "date": null,
- "time": null
}, - "presentValueWritable": "objectModeEnumSet.presentValueWritableWithPriority",
- "itemReference": "{hostname}:{deviceHostname}/Programming.AV1",
- "version": {
- "major": 1,
- "minor": 0
}, - "prioritySupported": true,
- "minPresValue": -1.6999999760721821e+38,
- "maxPresValue": 100,
- "units": "unitEnumSet.noUnits",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1",
- "covIncrement": 0.01,
- "connectedToInternalApplication": "noYesEnumSet.fanNo",
- "presentValue": 105,
- "status": "objectStatusEnumSet.osHighPriority",
- "attrChangeCount": 9,
- "defaultAttribute": "attributeEnumSet.presentValue",
- "id": "ce820989-5617-50bd-90ea-2fd95d1402ba"
}, - "effectivePermissions": {
- "canDelete": true,
- "canModify": true
}, - "views": [
- {
- "title": "Focus",
- "views": [
- {
- "title": "Basic",
- "views": [
- {
- "title": "Object",
- "properties": [
- "name",
- "description",
- "bacnetObjectType",
- "objectCategory"
], - "id": "viewGroupEnumSet.objectGrp"
}, - {
- "title": "Status",
- "properties": [
- "outOfService",
- "reliability",
- "currentCommandPriority",
- "alarmState",
- "overrideExpirationTime",
- "presentValueWritable"
], - "id": "viewGroupEnumSet.statusGrp"
}
], - "id": "groupTypeEnumSet.basicGrpType"
}, - {
- "title": "Advanced",
- "views": [
- {
- "title": "Engineering Values",
- "properties": [
- "itemReference",
- "version",
- "prioritySupported",
- "minPresValue",
- "maxPresValue"
], - "id": "viewGroupEnumSet.engValuesGrp"
}, - {
- "title": "Display",
- "properties": [
- "units",
- "displayPrecision",
- "covIncrement"
], - "id": "viewGroupEnumSet.displayGrp"
}, - {
- "title": "Internal Logic Interface",
- "properties": [
- "connectedToInternalApplication"
], - "id": "viewGroupEnumSet.internalLogicIfGrp"
}
], - "id": "groupTypeEnumSet.advancedGrpType"
}, - {
- "title": "Key",
- "views": [
- {
- "title": "None",
- "properties": [
- "presentValue",
- "status",
- "attrChangeCount",
- "defaultAttribute"
], - "id": "viewGroupEnumSet.noGrp"
}
], - "id": "groupTypeEnumSet.keyGrpType"
}
], - "id": "viewNameEnumSet.focusView"
}
], - "condition": {
- "presentValue": {
- "reliability": "reliabilityEnumSet.unreliableHigh",
- "priority": "writePriorityEnumSet.priorityCriticalEquipment"
}
}
}This operation modifies one or more attributes of an object. Note:
attributes must be updated in whole. For example, if you wish to modify an
attribute of metasysType struct which is modelled as a JSON object you
must include all elements of the struct. It is undefined what might happen
if you do not. The write could fail, the non-mentioned members may get their
default value or something else. This applies to any attribute that has a
JSON type of array or object. The entire attribute value must be written
even if you only wish to change one part of the value.
The request body contains an item property which contains one or more
properties and their new values.
The attributes of an object (and their schemas) can be discovered by looking at the different views of an object or by requesting all of the attributes.
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| item | object The attributes to update. |
{- "item": {
- "presentValue": 71.5
}
}Deletes the specified object.
Not all objects can be deleted (not even by an administrator). Examine the
effectivePermissions of an object to determine if it can be deleted by the
current user.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Objects support one or more views. Each view of an object contains a logical grouping of the object's attributes. This operation lists the collection of views that an object has.
Each entry in the response contains the id of a view, and also the
absolute URL used to request that view. Use Get an object
(/objects/{objectId}) to request a specific view by specifying the desired
id for the viewId query parameter.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| includeSchema | boolean Set this parameter to |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/views?includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- {
- "id": "viewNameEnumSet.focusView",
}, - {
- "id": "viewNameEnumSet.optionsView",
}
],
}Returns a set of attributes for an object. The attributes returned are considered public information for any authenticated user and therefore no special privileges are required to call this operation.
One of the attributes returned by this operation (for many objects) is the
default attribute (defaultAttribute). If the object has a default
attribute then the attribute named by the defaultAttribute property is
also included in the response. For example, the analog value (AV) object has
a defaultAttribute of attributeEnumSet.presentValue so presentValue is
included in the public view of an AV.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| includeSchema | boolean Every object can have a unique schema. Set this parameter to |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/publicView?includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This is an example of a public view for an AV object with schema included.
{- "objectType": "objectTypeEnumSet.avClass",
- "networkDeviceUrl": "https://{hostname}/api/v5/networkDevices/4d762b40-b3f5-5bed-bba9-d5820993cea7",
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/trendedAttributes",
- "item": {
- "name": "AV1",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "description": null,
- "objectCategory": "objectCategoryEnumSet.generalCategory",
- "status": "objectStatusEnumSet.osNormal",
- "alarmState": "objectStatusEnumSet.osNormal",
- "defaultAttribute": "attributeEnumSet.presentValue",
- "bacnetObjectType": "objectTypeEnumSet.bacAvClass",
- "overrideExpirationTime": {
- "date": null,
- "time": null
}, - "attrChangeCount": 110,
- "reliability": "reliabilityEnumSet.reliable",
- "version": {
- "major": 1,
- "minor": 0
}, - "presentValue": "0"
}, - "schema": {
- "type": "object",
- "language": "en-US",
- "title": "JCI AV",
- "version": "1.0",
- "properties": {
- "name": {
- "title": "Name",
- "category": "attributeCategoryEnumSet.nameCategory",
- "type": "string",
- "metasysType": "string"
}, - "itemReference": {
- "title": "Item Reference",
- "readOnly": true,
- "category": "attributeCategoryEnumSet.objectNameCategory",
- "type": "string",
- "metasysType": "string"
}, - "description": {
- "title": "Description",
- "oneOf": [
- {
- "type": "string"
}, - {
- "type": "null"
}
], - "metasysType": "string"
}, - "objectCategory": {
- "title": "Authorization Category",
- "category": "attributeCategoryEnumSet.objectCategoryCategory",
- "numberOfStates": 250,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectCategoryEnumSet"
}
]
}, - "status": {
- "title": "Status",
- "readOnly": true,
- "dynamic": true,
- "numberOfStates": 120,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectStatusEnumSet"
}
]
}, - "alarmState": {
- "title": "Alarm State",
- "readOnly": true,
- "dynamic": true,
- "numberOfStates": 120,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectStatusEnumSet"
}
]
}, - "default": {
- "title": "Default",
- "prioritized": true,
- "dynamic": true,
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}, - "defaultAttribute": {
- "title": "Default Attr Number",
- "readOnly": true,
- "oneOf": [
- {
- "type": "string"
}, - {
- "type": "null"
}, - {
- "$ref": "#attributeEnumSet"
}
], - "metasysType": "enum"
}, - "bacnetObjectType": {
- "title": "Object Type",
- "readOnly": true,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectTypeEnumSet"
}
]
}, - "overrideExpirationTime": {
- "title": "Override Expiration Time",
- "readOnly": true,
- "category": "attributeCategoryEnumSet.bacnetDateTimeCategory",
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "date": {
- "oneOf": [
- {
- "allOf": [
- {
- "$ref": "#metasys-date"
}, - {
- "required": [
- "year",
- "month",
- "dayOfMonth"
], - "display": [
- "year",
- "month",
- "dayOfMonth"
]
}
]
}, - {
- "type": "null"
}
], - "metasysType": "date",
- "title": "Date"
}, - "time": {
- "oneOf": [
- {
- "allOf": [
- {
- "$ref": "#metasys-time"
}, - {
- "required": [
- "hour",
- "minute",
- "second"
], - "display": [
- "hour",
- "minute",
- "second"
]
}
]
}, - {
- "type": "null"
}
], - "metasysType": "time",
- "title": "Time"
}
}
}, - "attrChangeCount": {
- "title": "Attr Change Count",
- "readOnly": true,
- "dynamic": true,
- "metasysType": "byte",
- "type": "integer",
- "minimum": 0,
- "maximum": 255
}, - "reliability": {
- "title": "Reliability",
- "numberOfStates": 116,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#reliabilityEnumSet_endAt_116"
}
]
}, - "version": {
- "title": "Version",
- "readOnly": true,
- "category": "attributeCategoryEnumSet.versionStructCategory",
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "major": {
- "metasysType": "byte",
- "type": "integer",
- "minimum": 0,
- "maximum": 255,
- "title": "Major"
}, - "minor": {
- "metasysType": "byte",
- "type": "integer",
- "minimum": 0,
- "maximum": 255,
- "title": "Minor"
}
}
}
}, - "definitions": {
- "objectCategoryEnumSet": {
- "title": "Authorization Category",
- "$id": "#objectCategoryEnumSet",
- "setId": 33
}, - "objectStatusEnumSet": {
- "title": "Object Status",
- "$id": "#objectStatusEnumSet",
- "setId": 505
}, - "attributeEnumSet": {
- "title": "Attribute",
- "$id": "#attributeEnumSet",
- "setId": 509
}, - "objectTypeEnumSet": {
- "title": "Object Type",
- "$id": "#objectTypeEnumSet",
- "setId": 508
}, - "metasys-date": {
- "$id": "#metasys-date",
- "title": "date",
- "description": "Metasys Date",
- "type": "object",
- "properties": {
- "year": {
- "type": "integer",
- "description": "Year"
}, - "month": {
- "type": "integer",
- "minimum": 1,
- "maximum": 12,
- "description": "Month"
}, - "dayOfMonth": {
- "type": "integer",
- "minimum": 1,
- "maximum": 31,
- "description": "Day of Month"
}, - "dayOfWeek": {
- "type": "integer",
- "minimum": 1,
- "maximum": 7,
- "description": "Day of Week"
}
}, - "additionalProperties": false
}, - "metasys-time": {
- "$id": "#metasys-time",
- "title": "time",
- "description": "Metasys time",
- "type": "object",
- "properties": {
- "hour": {
- "type": "integer",
- "minimum": 0,
- "maximum": 23,
- "description": "Hour"
}, - "minute": {
- "type": "integer",
- "minimum": 0,
- "maximum": 59,
- "description": "Minute"
}, - "second": {
- "type": "integer",
- "minimum": 0,
- "maximum": 59,
- "description": "Second"
}, - "hundredth": {
- "type": "integer",
- "minimum": 0,
- "maximum": 99,
- "description": "Hundredths"
}
}, - "additionalProperties": false
}, - "reliabilityEnumSet_endAt_116": {
- "title": "Reliability",
- "$id": "#reliabilityEnumSet_endAt_116",
- "setId": 503
}
}
}, - "effectivePermissions": {
- "canDelete": true,
- "canModify": true
}, - "condition": { }
}Returns an object payload with a JSON schema that contains all of the
properties of the object. Each property entry contains only a partial schema
for that property. (To discover the full schema of an attribute use
/objects/{objectId}?includeSchema=true or
/objects/{objectId}/attributes/{attrId}?includeSchema=true
The item section of the payload will contain at most one attribute, the
defaultAttribute. The item section will be completely missing if the
object does not have a default attribute.
There will be no views or condition sections like a typical object payload.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "item": {
- "defaultAttribute": "attributeEnumSet.presentValue"
}, - "schema": {
- "type": "object",
- "language": "en-US",
- "title": "JCI AV",
- "version": "1.0",
- "properties": {
- "presentValue": {
- "title": "Present Value",
- "prioritized": true,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "reliability": {
- "title": "Reliability",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "outOfService": {
- "title": "Out Of Service",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "statusFlags": {
- "title": "Status Flags",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "bitString"
}, - "eventState": {
- "title": "Event State",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "presentValueWritable": {
- "title": "Present Value Writable",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "connectedToInternalApplication": {
- "title": "Connected to Internal Application",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "bacnetExposed": {
- "title": "BACnet Exposed",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "maxPresValue": {
- "title": "Max Value",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "minPresValue": {
- "title": "Min Value",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "covIncrement": {
- "title": "COV Increment",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "units": {
- "title": "Units",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "displayPrecision": {
- "title": "Display Precision",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "propertyRefValue": {
- "title": "Property Ref Value",
- "readOnly": true,
- "prioritized": false,
- "metasysType": "attributeReference",
- "oneOf": [
- {
- "$ref": "#attribute-reference"
}
]
}, - "connectedTo": {
- "title": "Connected To",
- "prioritized": false,
- "metasysType": "attributeReference",
- "oneOf": [
- {
- "$ref": "#attribute-reference"
}
]
}, - "connectedStatus": {
- "title": "Connected Status",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "direction": {
- "title": "Direction",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "prioritySupported": {
- "title": "Priority Supported",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "relinquishDefault": {
- "title": "Relinquish Default",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "restoreCommandPriority": {
- "title": "Restore Command Priority",
- "prioritized": false,
- "type": "string",
- "metasysType": "bitString"
}, - "priorityArray": {
- "title": "Priority Array",
- "readOnly": true,
- "prioritized": false,
- "type": "array",
- "metasysType": "array"
}, - "overrideExpirationTime": {
- "title": "Override Expiration Time",
- "readOnly": true,
- "prioritized": false,
- "type": "object",
- "metasysType": "struct"
}, - "currentCommandPriority": {
- "title": "Current Command Priority",
- "readOnly": true,
- "prioritized": false,
- "metasysType": "ushort",
- "type": "integer",
- "minimum": 0,
- "maximum": 65535
}, - "itemReference": {
- "title": "Item Reference",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "name": {
- "title": "Name",
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "objectName": {
- "title": "Object Name",
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "description": {
- "title": "Description",
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "status": {
- "title": "Status",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "enabled": {
- "title": "Enabled",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "executionPriority": {
- "title": "Execution Priority",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "objectCategory": {
- "title": "Authorization Category",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "alarmState": {
- "title": "Alarm State",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "bacnetObjectType": {
- "title": "Object Type",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "objectIdentifier": {
- "title": "Object Identifier",
- "readOnly": true,
- "prioritized": false,
- "metasysType": "bacOid",
- "oneOf": [
- {
- "$ref": "#bacoid"
}
]
}, - "propertyList": {
- "title": "Property List",
- "readOnly": true,
- "prioritized": false,
- "type": "array",
- "metasysType": "listof"
}
}, - "definitions": {
- "object-reference": {
- "$id": "#object-reference",
- "title": "Object reference data type",
- "type": "object",
- "oneOf": [
- {
- "properties": {
- "objectReference": {
- "format": "fully-qualified-reference",
- "type": "string"
}, - "referencedObject": {
- "type": "object",
- "properties": {
- "objectName": {
- "type": "string"
}, - "objectUrl": {
- "type": "string",
- "format": "uri"
}
}, - "readOnly": true
}
}, - "required": [
- "objectReference"
]
}, - {
- "properties": {
- "objectBACoid": {
- "readOnly": true,
- "oneOf": [
- {
- "$ref": "#bacoid"
}
]
}, - "deviceAddress": {
- "readOnly": true,
- "type": "string"
}, - "deviceBACoid": {
- "readOnly": true,
- "oneOf": [
- {
- "$ref": "#bacoid"
}
]
}
}, - "required": [
- "objectBACoid"
], - "additionalProperties": false
}
]
}, - "attribute-reference": {
- "$id": "#attribute-reference",
- "title": "Attribute reference data type",
- "type": "object",
- "allOf": [
- {
- "$ref": "#object-reference"
}, - {
- "properties": {
- "if": {
- "required": [
- "objectReference"
]
}, - "then": {
- "properties": {
- "referencedObject": {
- "properties": {
- "attributeUrl": {
- "type": "string",
- "metasysType": "string",
- "format": "uri"
}, - "attributeName": {
- "type": "string",
- "metasysType": "string"
}
}
}
}
}
}
}
]
}, - "bacoid": {
- "type": "object",
- "$id": "#bacoid",
- "title": "A definition for the BACoid data type",
- "properties": {
- "bacnetObjectType": {
- "title": "BACnet Object Type",
}, - "instance": {
- "type": "integer",
- "title": "Instance Number",
- "minimum": 0,
- "maximum": 4194303
}
}, - "required": [
- "bacnetObjectType",
- "instance"
], - "additionalProperties": false
}
}
}
}Returns an object payload containing the specified attribute. Invoke this
operation with a valid METASYS-SUBSCRIBE header to create a subscription
for changes to that attribute, rather than returning a value. The current
value and any updates to the attribute are instead sent over the specified
stream.
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| attributeId required | string Examples:
metasysEnum: attributeEnumSet The attribute to read. The acceptable values for this parameter come from the See also:
|
| includeSchema | boolean Set this parameter to |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes/presentValue?includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
{- "item": {
- "presentValue": 72.5
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}, - "schema": {
- "type": "object",
- "language": "en-US",
- "title": "JCI AV",
- "version": "1.0",
- "properties": {
- "presentValue": {
- "title": "Present Value",
- "prioritized": true,
- "dynamic": true,
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}
}
}
}Returns a payload that lists all of the commands that an object supports.
Each command entry has an invokeUrl property, which is the URL needed to
invoke the command. In addition, each command entry has a
commandBodySchema property, which is a JSON schema that describes the
acceptable payload for the command. Commands are invoked using the HTTP
method PUT along with the invokeUrl and acceptable body.
Note: Some objects, such as multi-state values (MV) and binary values (BV),
may list a command that has a commandSet property and a property named
aggregateCommand with a value of true instead of invokeUrl. This
commandSet lists one or more commands. This entry is not a true command
but rather provides a hint to graphical user interfaces on how they may want
to group the commands of the commandSet under one command name. For
example, an MV object lists a command with the identifier
commandIdEnumSet.adjustCommand. This is not an actual command on an MV.
Instead the actual commands that could be used to present this command in a
UI are listed in the commandSet and they have identifiers like
commandIdEnumSet.multistate0Command. The Metasys User Interface displays
all of these commands as a single adjust command with the titles of the
individual commands as the parameter to send.
Licensing Restrictions
Requires Monitoring and Commanding API license.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/commands \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- {
- "id": "commandIdEnumSet.adjustCommand",
- "title": "Adjust",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "priority": {
- "oneOf": [
- {
- "$ref": "#writePriorityEnumSet"
}, - {
- "type": "null"
}
]
}, - "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.valueCmdparm",
- "title": "Value",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999998e+38,
- "maximum": 1.69999998e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 72.5
}
], - "minItems": 1,
- "maxItems": 1
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false,
- "definitions": {
- "writePriorityEnumSet": {
- "title": "Write Priority",
- "$id": "#writePriorityEnumSet",
- "setId": 1
}
}
}
}, - {
- "id": "commandIdEnumSet.overrideCommand",
- "title": "Operator Override",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.valueCmdparm",
- "title": "Value",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999998e+38,
- "maximum": 1.69999998e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 72.5
}
], - "minItems": 1,
- "maxItems": 1
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false
}
}, - {
- "id": "commandIdEnumSet.temporaryOverrideCommand",
- "title": "Temporary Override",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.valueCmdparm",
- "title": "Value",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999998e+38,
- "maximum": 1.69999998e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 72.5
}, - {
- "id": "commandParmsEnumSet.hoursCmdparm",
- "title": "Hours",
- "metasysType": "ulong",
- "type": "integer",
- "minimum": 0,
- "maximum": 100,
- "default": 0
}, - {
- "id": "commandParmsEnumSet.minutesCmdparm",
- "title": "Minutes",
- "metasysType": "ulong",
- "type": "integer",
- "minimum": 0,
- "maximum": 59,
- "default": 0
}
], - "minItems": 3,
- "maxItems": 3
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false
}
}, - {
- "id": "commandIdEnumSet.overrideReleaseCommand",
- "title": "Release Operator Override",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false
}
}, - {
- "id": "commandIdEnumSet.releaseCommand",
- "title": "Release",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.attributeCmdparm",
- "title": "Attribute",
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#attributeEnumSet"
}
], - "default": "attributeEnumSet.presentValue"
}, - {
- "id": "commandParmsEnumSet.priorityCmdparm",
- "title": "Priority",
- "numberOfStates": 17,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#writePriorityEnumSet"
}
], - "default": "writePriorityEnumSet.priorityDefault"
}
], - "minItems": 2,
- "maxItems": 2
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false,
- "definitions": {
- "attributeEnumSet": {
- "title": "Attribute",
- "$id": "#attributeEnumSet",
- "allOf": [
- {
- "oneOf": [
- {
- "const": "attributeEnumSet.presentValue",
- "title": "Present Value",
- "memberId": 85
}
]
},
], - "setId": 509
}, - "writePriorityEnumSet": {
- "title": "Write Priority",
- "$id": "#writePriorityEnumSet",
- "setId": 1
}
}
}
}, - {
- "id": "commandIdEnumSet.releaseAllCommand",
- "title": "Release All",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.attributeCmdparm",
- "title": "Attribute",
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#attributeEnumSet"
}
], - "default": "attributeEnumSet.presentValue"
}
], - "minItems": 1,
- "maxItems": 1
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false,
- "definitions": {
- "attributeEnumSet": {
- "title": "Attribute",
- "$id": "#attributeEnumSet",
- "allOf": [
- {
- "oneOf": [
- {
- "const": "attributeEnumSet.presentValue",
- "title": "Present Value",
- "memberId": 85
}
]
},
], - "setId": 509
}
}
}
}, - {
- "id": "commandIdEnumSet.enableAlarmsCommand",
- "title": "Enable Alarms",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false
}
}, - {
- "id": "commandIdEnumSet.disableAlarmsCommand",
- "title": "Disable Alarms",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}
}, - "required": [ ],
- "additionalProperties": false
}
}
], - "effectivePermissions": {
- "canInvoke": [
- "commandIdEnumSet.adjustCommand",
- "commandIdEnumSet.overrideCommand",
- "commandIdEnumSet.temporaryOverrideCommand",
- "commandIdEnumSet.overrideReleaseCommand",
- "commandIdEnumSet.releaseCommand",
- "commandIdEnumSet.releaseAllCommand",
- "commandIdEnumSet.enableAlarmsCommand",
- "commandIdEnumSet.disableAlarmsCommand"
]
}
}Used to send a command to an object. The payloads of commands differ, but
they share some similarities. To learn the specifics of the commands of an
object use List commands.
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| commandId required | string Example: adjustCommand metasysEnum: commandIdEnumSet The identifier of the command to send. The acceptable values for this parameter come from the See also:
|
The body of a command is defined by the commandBodySchema. The
commandBodySchema is a property of every command returned by the
List commands operation.
| priority | string (write-priority-enum-set) Enum: "writePriorityEnumSet.priorityNone" "writePriorityEnumSet.priorityManualEmergency" "writePriorityEnumSet.priorityFireApplications" "writePriorityEnumSet.priority3" "writePriorityEnumSet.priority4" "writePriorityEnumSet.priorityCriticalEquipment" "writePriorityEnumSet.priorityMinimumOnOff" "writePriorityEnumSet.priorityHeavyEquipDelay" "writePriorityEnumSet.priorityOperatorOverride" "writePriorityEnumSet.priority9" "writePriorityEnumSet.priority10" "writePriorityEnumSet.priorityDemandLimiting" "writePriorityEnumSet.priority12" "writePriorityEnumSet.priorityLoadRolling" "writePriorityEnumSet.priority14" "writePriorityEnumSet.prioritySchedulingOst" "writePriorityEnumSet.priorityDefault" metasysType: enum metasysEnum: writePriorityEnumSet |
| parameters | Array of any >= 0 items |
| annotation | string |
This body is used with the adjust command of an Analog Value (AV).
It sends the value 72.5 along with an annotation about why the
command was invoked. The URL for this command is
/objects/{objectId}/commands/adjustCommand
{- "parameters": [
- 72.5
], - "annotation": "Increase the set point to make it warmer."
}"Success"Many objects support nested objects. The obvious examples of this are
folder objects and device objects. Less obvious examples include objects
like analog value and multi-state value objects (which can have child
objects like integrations). This operation lists the types of objects that
can be created under an object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/supportedChildTypes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The supported child types of a folder.
[- {
- "objectType": "mvClass",
- "description": "MV",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "mcClass",
- "description": "Multiple Command",
- "version": "2.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "intlClass",
- "description": "Interlock",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "calendarClass",
- "description": "Calendar",
- "version": "3.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "avClass",
- "description": "AV",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "bvClass",
- "description": "BV",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "optimalStartClass",
- "description": "Optimal Start",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "containerClass",
- "description": "Folder",
- "version": "1.0",
- "classification": "folder",
- "isAuthorized": true
}, - {
- "objectType": "globalDataClass",
- "description": "Global Data",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "signalSelectClass",
- "description": "Signal Select",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "pulseMeterClass",
- "description": "Pulse Meter",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "autoShutdownClass",
- "description": "Auto Shutdown",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "eeClass",
- "description": "Event Enrollment",
- "version": "2.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "bgrpClass",
- "description": "Group",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "flexAccumulatorClass",
- "description": "Accumulator",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "ieiejEdcClass",
- "description": "Electric Demand Control",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "ieiejGlcClass",
- "description": "Generator Load Control",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "solarClockClass",
- "description": "Solar Clock",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "scheduleClass",
- "description": "Schedule",
- "version": "3.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "loopClass",
- "description": "Loop",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "notificationClass",
- "description": "Notification",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "dataBroadcastClass",
- "description": "Data Broadcast",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "systemClass",
- "description": "Program",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "trendLogNoextensionClass",
- "description": "Trend Log",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}
]Retrieves all equipment points mapped to attributes of this object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "shortName" Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName" Example: sort=shortName The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/points?page=1&pageSize=100&sort=shortName' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 1,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-T",
- "label": "Zone Temperature",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}
],
}This operation is used to invoke multiple operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request.
In this version of the API, the only objects related operation that can be used in a batch is Get attribute value.
If this operation is invoked with a valid METASYS-CALL-ASYNC header it will
cause a temporary subscription to be created for the attributes in the request
and rather than returning any values, the current values and any updates to the
attributes will be sent over the specified stream.
Licensing Restrictions
Requires Monitoring and Commanding API license.
(INTERNAL) In addition to Get attribute value, internal clients may also use Change order of objects and Lookup object identifier. All of the operations in a batch must be the same. You cannot mix Get attribute value with Change order of objects order and/or Lookup object identifier.
(INTERNAL) The Change order of objects operation supports both synchronous and
asynchronous calling. METASYS-CALL-ASYNC header is required for async version.
If the header is not included, this will be considered as synchronous operation
and the API will return the synchronous response only. The async version of
Change order of objects will send one objects.ordering.update event per
sub-request. The payload for the event will match the payload defined in the
Change order of objects operation.
(PRIVATE) Asynchronous version of change of order of objects implementation details
A batch request to change object ordering follows the schema for this operation.
{
"method": "PATCH",
"requests": [
{
"id": "1",
"relativeUrl": "3f8c1e32-4504-5d0a-9d8e-b695b059e272/objects/ordering",
"body": {
"items": [
"56d85c80-2741-5d4f-8f97-02877dd2c0e6",
"54c74311-4492-5f17-8caa-6ab69619402d"
]
}
}
]
}
Just like the single version of object ordering, each request should have synchronous error checking performed: duplicated child ids, invalid child ids, malformed request. (This could be done by delegating the call to the single versions or in some other way if that's more efficient.)
If the overall batch request is well formed and has at least one sub-request
that is valid, then the HTTP response should return a status of 200 . Each
sub-response that corresponds to a valid sub-request should have a status of
202 (Accepted) with a null body (The body property is required but null
is allowed as an option). The sub-requests that are not valid should return
sub-responses with error payloads following the schema already defined for this
batch operation:
parentId is invalid(parent id doesn't exist or
provided guid is not valid parent)error is required.statusEnumSet,
if possible)Here's an example that shows a response to one valid request and one invalid request.
{
"requests": [
{
"id": "2",
"status": 202,
"body": null
}
{
"id": "3",
"status": 400,
"body": {
"error": {
"statusName": "api:error.parentObjectNotFound",
"message": "Parent id not found",
"details": "Object not found: 7ef86382-5cab-57cd-865c-de485916f587"
}
}
}
]
}
The message string was chosen because it appears to be our standard error
message for all 400 errors. The details provide a user with more information
on what was wrong. The api:error.parentObjectNotFound value was chosen for
statusName because it's display string is "Object not found"
If the overall batch request is malformed or has no valid sub-requests then the
HTTP response should return a 400 status code. The existing schema for a 400
response is simply a string. Provide as informative of a string as possible.
(Test with payloads of wrong type, without method, without requests, with
every item in requests having errors. )
(PRIVATE) Synchronous version of change of order of objects implementation details
A batch request to change object ordering follows the schema for this operation. Note: Async header should not be passed.
{
"method": "PATCH",
"requests": [
{
"id": "1",
"relativeUrl": "3f8c1e32-4504-5d0a-9d8e-b695b059e272/objects/ordering",
"body": {
"items": [
"56d85c80-2741-5d4f-8f97-02877dd2c0e6",
"54c74311-4492-5f17-8caa-6ab69619402d"
]
}
}
]
}
Just like the single version of object ordering, each request should have synchronous error checking performed: duplicated child ids, invalid child ids, malformed request. (This could be done by delegating the call to the single versions or in some other way if that's more efficient.)
If the overall batch request is well formed and all the sub-requests are valid,
then the HTTP response should return a status of 200 . Each sub-response that
corresponds to a valid sub-request should have a status of 202 (Accepted) with
a null body (The body property is required but null is allowed as an
option).
Error scenarios are same as async version of Change order of Objects.
Here's an example that shows a response to one valid request and one invalid request.
{
"requests": [
{
"id": "2",
"status": 202,
"body": null
}
{
"id": "3",
"status": 400,
"body": {
"error": {
"statusName": "api:error.parentObjectNotFound",
"message": "Parent id not found",
"details": "Object not found: 7ef86382-5cab-57cd-865c-de485916f587"
}
}
}
]
}
The message string was chosen because it appears to be our standard error
message for all 400 errors. The details provide a user with more information
on what was wrong. The api:error.parentObjectNotFound value was chosen for
statusName because it's display string is "Object not found"
If the overall batch request is malformed or has no valid sub-requests then the
HTTP response should return a 400 status code. A 400 response follows the
standard error message schema. (Test with payloads of wrong type, without
method, without requests, with every item in requests having errors. )
(INTERNAL) Lookup object identifier implementation details
A batch request to lookup object identifier follows the schema for this operation.
{
"method": "GET",
"requests": [
{
"id": "1",
"relativeUrl": "identifiers?fqr=adx:nae23/Programming.AV1"
},
{
"id": "2",
"relativeUrl": "identifiers?fqr=adx:nae23/Programming.AV2"
}
]
}
Just like the single version of lookup object identifier, each request should have error checking performed: duplicated child ids, invalid child ids, malformed request. (This could be done by delegating the call to the single versions or in some other way if that's more efficient.)
If the overall batch request is well formed and all the sub-requests are valid,
then the HTTP response should return a status of 200 . Each sub-response that
corresponds to a valid sub-request should have a status of 200 (OK) with a
object identifier as string body.
Error scenarios are same as single version of lookup object identifier.
Here's an example that shows a response to one valid request and one invalid request.
{
"requests": [
{
"id": "1",
"status": 200,
"body": "1817c63a-a043-5231-bf07-bb51c83db8e8"
}
{
"id": "2",
"status": 400,
"body": {
"message": "Invalid FQR."
}
}
]
}
The message string is the reason why the request is failed.
If the overall batch request is malformed or has no valid sub-requests then the
HTTP response should return a 400 status code. A 400 response follows the
standard error message schema. (Test with payloads of wrong type, without
method, without requests, with every item in requests having errors. )
See also:
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
| METASYS-CALL-ASYNC | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b visibility: private (PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response. See also: |
| method required | string Enum: "GET" "PATCH" The HTTP method to use for each request. This property is
restricted to (INTERNAL) The method |
required | Array of objects non-empty A collection of entries that represent the operations to invoke. |
This example shows a request body that will read the
presentValue and status from 3 different objects using
sequential numbers as request identifiers.
This example shows the use of sequential numeric values used as request identifiers but any unique strings can be used.
{- "method": "GET",
- "requests": [
- {
- "id": "1",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/attributes/presentValue"
}, - {
- "id": "2",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/attributes/status"
}, - {
- "id": "3",
- "relativeUrl": "c82d160b-884c-5eac-bad4-89754f0069e0/attributes/presentValue"
}, - {
- "id": "4",
- "relativeUrl": "c82d160b-884c-5eac-bad4-89754f0069e0/attributes/status"
}, - {
- "id": "5",
- "relativeUrl": "3abd9027-c572-5f6d-9de6-bfc044f899dc/attributes/presentValue"
}, - {
- "id": "6",
- "relativeUrl": "3abd9027-c572-5f6d-9de6-bfc044f899dc/attributes/status"
}
]
}This example shows the response to a read multiple attributes
request. Each operation response is uniquely identified by the
corresponding identifier (id) from the request.
{- "responses": [
- {
- "id": "1",
- "status": 200,
- "body": {
- "item": {
- "presentValue": 78.5
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}
}
}, - {
- "id": "2",
- "status": 200,
- "body": {
- "item": {
- "status": "objectStatusEnumSet.osNormal"
}, - "condition": { }
}
}, - {
- "id": "3",
- "status": 200,
- "body": {
- "item": {
- "presentValue": 50
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}
}
}, - {
- "id": "4",
- "status": 200,
- "body": {
- "item": {
- "status": "objectStatusEnumSet.osLowAlarm"
}, - "condition": { }
}
}, - {
- "id": "5",
- "status": 200,
- "body": {
- "item": {
- "presentValue": 78.5
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}
}
}, - {
- "id": "6",
- "status": 200,
- "body": {
- "item": {
- "status": "objectStatusEnumSet.osNormal"
}, - "condition": { }
}
}
]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
This is a bulk operation that creates one or more objects.
| parentId required | string The ID of the parent object. The new object will be created under this object. |
| localUniqueIdentifier required | string <= 32 characters ^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$ A string that is locally unique within the context of the parent object
for identifying the new object. This string will be the last component of
the The value must not contain any control characters or any of the following
characters: |
| objectType required | string metasysType: enum metasysEnum: objectTypeEnumSet The type of object to create. The values for this property come from the See also:
|
| item | object The This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time. |
This shows a request to create two mapper objects.
[- {
- "parentId": "89940499-81df-5c1f-9ae6-5054f3f7845f",
- "objectType": "bacnetAvClass",
- "localUniqueIdentifier": "AV-3000224",
- "item": {
- "name": "oas1/Floor 1.ZN-T",
- "objectCategory": "objectCategoryEnumSet.generalCategory",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1",
- "instanceNumber": "3000224"
}
}, - {
- "parentId": "89940499-81df-5c1f-9ae6-5054f3f7845f",
- "objectType": "bacnetBvClass",
- "localUniqueIdentifier": "BV-3000226",
- "item": {
- "name": "oas1/Floor 1.OCC",
- "objectCategory": "objectCategoryEnumSet.generalCategory",
- "statesText": "twostateEnumSet.binarypvEnumSet",
- "userSelectedStatesText": false,
- "instanceNumber": "3000226"
}
}
][- {
- "guid": "1ed61f8b-cc5d-5118-a13d-25d0493ca47f",
- "localUniqueIdentifier": "AV-3000224",
- "reference": "{hostname}:{deviceHostname}/BACnet.Device-501583.AV-3000224",
- "creationResponse": {
- "statusCode": 200,
- "message": null,
- "messageDetails": null
}
}, - {
- "guid": "f7c7d3c1-05f6-500d-b02a-c7b9054e2437",
- "localUniqueIdentifier": "BV-3000226",
- "reference": "{hostname}:{deviceHostname}/BACnet.Device-501583.BV-3000226",
- "creationResponse": {
- "statusCode": 200,
- "message": null,
- "messageDetails": null
}
}
]Modify a COV subscription by replacing the set of attributes you are subscribed to with a new set of attributes.
How COV works? please check Batch Subscriptions And Async Operations
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
Used to convey the desired subscription.
required | Array of objects A collection of object id and attribute name that are requested for subscription. |
{- "items": [
- {
- "id": "1",
- "objectId": "82b6f2d5-6fed-5074-b611-94dd40028312",
- "attributeId": "attributeEnumSet.presentValue"
}, - {
- "id": "2",
- "objectId": "82b6f2d5-6fed-5074-b611-94dd40028313",
- "attributeId": "attributeEnumSet.status"
}
]
}This example shows the response to a modify subscription with
multiple objects and attributes request. first operation returns
status of 202 signifying it was accepted. second operation
returned with status a 400 to indicate an object not found issue,
third operation returned with status a 400 to indicate an
attribute not found issue, fourth operation returned with status a
401 to indicate an attribute not authorized issue and last
operation returned with status a 400 to indicate multiple errors
issue with the request.
{- "responses": [
- {
- "id": "1",
- "status": 202,
- "body": null
}, - {
- "id": "2",
- "status": 400,
- "body": {
- "error": {
- "statusName": "api:error.objectNotFound",
- "message": "Object not found.",
- "details": {
- "objectId": [
- "e9bf66bd-22f8-425b-82a4-44ba153d79c7"
]
}
}
}
}, - {
- "id": "3",
- "status": 400,
- "body": {
- "error": {
- "statusName": "api:error.attributeNotFound",
- "message": "Invalid Attribute number for this object.",
- "details": {
- "attributeId": [
- "attributeEnumSet.pastValue"
]
}
}
}
}, - {
- "id": "4",
- "status": 401,
- "body": {
- "error": {
- "statusName": "api:error.attributeNotAuthorized",
- "message": "User is not authorized to view this attribute.",
- "details": {
- "attributeId": [
- "attributeEnumSet.outOfService"
]
}
}
}
}, - {
- "id": "5",
- "status": 400,
- "body": {
- "error": {
- "statusName": "api:error.multipleErrors",
- "message": "Multiple errors were encountered; please see 'innerErrors'.",
- "innerErrors": [
- {
- "statusName": "api:error.objectNotFound",
- "message": "Object not found.",
- "details": {
- "objectId": [
- "e9bf66bd-22f8-425b-82a4-44ba153d79c7"
]
}
}, - {
- "statusName": "api:error.attributeNotFound",
- "message": "Invalid Attribute number for this object.",
- "details": {
- "attributeId": [
- "attributeEnumSet.pastValue"
]
}
}
]
}
}
}
]
}Deletes a COV subscription by subscriptionId.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/objects/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This operation retrieves the specified enumeration as a JSON schema. The path of this operation appears in several schemas of object payloads.
To get a list of all enumerations fetch the enumerationSetNamesEnumSet:
GET /schemas/enums/enumerationSetNamesEnumSet
See also:
| enumId required | string Examples:
metasysType: enum The enumeration to retrieve. The acceptable values for this parameter come from the
|
curl --request GET \ --url https://metasys-server.example.com/api/v5/schemas/enums/writePriorityEnumSet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "title": "Write Priority",
- "setId": 1,
- "oneOf": [
- {
- "const": "writePriorityEnumSet.priorityNone",
- "title": "0 (No Priority)",
- "memberId": 0
}, - {
- "const": "writePriorityEnumSet.priorityManualEmergency",
- "title": "1 (Manual Life Safety)",
- "memberId": 1
}, - {
- "const": "writePriorityEnumSet.priorityFireApplications",
- "title": "2 (Auto Life Safety)",
- "memberId": 2
}, - {
- "const": "writePriorityEnumSet.priority3",
- "title": "3 (Application)",
- "memberId": 3
}, - {
- "const": "writePriorityEnumSet.priority4",
- "title": "4 (Application)",
- "memberId": 4
}, - {
- "const": "writePriorityEnumSet.priorityCriticalEquipment",
- "title": "5 (Critical Equipment)",
- "memberId": 5
}, - {
- "const": "writePriorityEnumSet.priorityMinimumOnOff",
- "title": "6 (Minimum On Off)",
- "memberId": 6
}, - {
- "const": "writePriorityEnumSet.priorityHeavyEquipDelay",
- "title": "7 (Heavy Equip Delay)",
- "memberId": 7
}, - {
- "const": "writePriorityEnumSet.priorityOperatorOverride",
- "title": "8 (Operator Override)",
- "memberId": 8
}, - {
- "const": "writePriorityEnumSet.priority9",
- "title": "9 (Application)",
- "memberId": 9
}, - {
- "const": "writePriorityEnumSet.priority10",
- "title": "10 (Application)",
- "memberId": 10
}, - {
- "const": "writePriorityEnumSet.priorityDemandLimiting",
- "title": "11 (Demand Limiting)",
- "memberId": 11
}, - {
- "const": "writePriorityEnumSet.priority12",
- "title": "12 (Application)",
- "memberId": 12
}, - {
- "const": "writePriorityEnumSet.priorityLoadRolling",
- "title": "13 (Load Rolling)",
- "memberId": 13
}, - {
- "const": "writePriorityEnumSet.priority14",
- "title": "14 (Application)",
- "memberId": 14
}, - {
- "const": "writePriorityEnumSet.prioritySchedulingOst",
- "title": "15 (Scheduling)",
- "memberId": 15
}, - {
- "const": "writePriorityEnumSet.priorityDefault",
- "title": "16 (Default)",
- "memberId": 16
}
]
}This endpoint retrieves a schema for a specific objectType. The schema
describes the properties that can be set when creating an object of the
specific type.
| objectType required | string Examples:
metasysEnum: objectTypeEnumSet The type of object The acceptable values for this parameter come from the See also:
|
| parentId required | string Example: parentId=2993aed9-5765-5641-889c-40ec968c8a82 The object under which this new object will be created. |
| extendedProperty | string Examples:
metasysEnum: attributeEnumSet The attribute to extend. Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions). The acceptable values for this parameter come from the See also:
|
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/schemas/objectTypes/objectTypeEnumSet.avClass?parentId=2993aed9-5765-5641-889c-40ec968c8a82&extendedProperty=attributeEnumSet.presentValue' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This schema describes the properties that can be configured when creating an object of the type avClass.
{- "schema": {
- "$comment": "Some parts of this schema have been truncated for space reasons. Where this has been done it has been noted.",
- "type": "object",
- "title": "JCI AV",
- "language": "en-us",
- "version": "1.0",
- "properties": {
- "name": {
- "title": "Name",
- "category": "attributeCategoryEnumSet.nameCategory",
- "type": "string",
- "metasysType": "string",
- "maxLength": 400,
- "default": ""
}, - "description": {
- "title": "Description",
- "oneOf": [
- {
- "type": "string"
}, - {
- "type": "null"
}
], - "metasysType": "string",
- "maxLength": 64
}, - "bacnetObjectType": {
- "title": "Object Type",
- "readOnly": true,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectTypeEnumSet"
}
], - "default": "objectTypeEnumSet.bacAvClass"
}, - "objectCategory": {
- "title": "Authorization Category",
- "category": "attributeCategoryEnumSet.objectCategoryCategory",
- "numberOfStates": 250,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectCategoryEnumSet"
}
], - "default": "objectCategoryEnumSet.generalCategory"
}, - "prioritySupported": {
- "title": "Priority Supported",
- "type": "boolean",
- "metasysType": "bool",
- "default": true
}, - "minPresValue": {
- "title": "Min Value",
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": -1.69999997607218e+38
}, - "maxPresValue": {
- "title": "Max Value",
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 1.69999997607218e+38
}, - "units": {
- "title": "Units",
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#unitEnumSet"
}
], - "default": "unitEnumSet.noUnits"
}, - "displayPrecision": {
- "title": "Display Precision",
- "numberOfStates": 13,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#displayPrecisionEnumSet_endAt_13"
}
], - "default": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "covIncrement": {
- "title": "COV Increment",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": 0,
- "default": 0.01
}, - "relinquishDefault": {
- "title": "Relinquish Default",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999997607218e+38,
- "maximum": 1.69999997607218e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 0
}, - "restoreCommandPriority": {
- "title": "Restore Command Priority",
- "category": "attributeCategoryEnumSet.restoreCommandPriorityCategory",
- "type": "array",
- "metasysType": "flags",
- "maxItems": 4,
- "minItems": 4,
- "items": {
- "type": "array",
- "items": [
- {
- "$ref": "#restorePriorityEnumSet"
}, - {
- "type": "boolean"
}
]
}, - "uniqueItems": true,
- "default": [
- [
- "restorePriorityEnumSet.7",
- true
], - [
- "restorePriorityEnumSet.10",
- false
], - [
- "restorePriorityEnumSet.12",
- false
], - [
- "restorePriorityEnumSet.15",
- false
]
]
}, - "connectedTo": {
- "title": "Connected To",
- "oneOf": [
- {
- "type": "null"
}, - {
- "$ref": "#attribute-reference"
}
], - "metasysType": "attributeReference",
- "attributeFilter": "basic"
}, - "direction": {
- "title": "Direction",
- "numberOfStates": 3,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#connectionDirectionSet_endAt_3"
}
], - "default": "connectionDirectionSet.notConnected"
}, - "priorityForWritingToConnected": {
- "title": "Priority For Writing to Connected Object",
- "metasysType": "byte",
- "type": "integer",
- "minimum": 1,
- "maximum": 16,
- "default": 16
}
}, - "definitions": {
- "objectTypeEnumSet": {
- "title": "Object Type",
- "$id": "#objectTypeEnumSet",
- "allOf": [
- {
- "oneOf": [
- {
- "const": "objectTypeEnumSet.bacAvClass",
- "title": "AV",
- "memberId": 2
}
]
},
], - "setId": 508
}, - "objectCategoryEnumSet": {
- "title": "Authorization Category",
- "$id": "#objectCategoryEnumSet",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "objectCategoryEnumSet.hvacCategory",
- "title": "HVAC",
- "memberId": 0
}
]
},
], - "setId": 33
}, - "unitEnumSet": {
- "title": "Unit",
- "$id": "#unitEnumSet",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "unitEnumSet.squareMeters",
- "title": "sq meter",
- "memberId": 0
}
]
},
], - "setId": 507
}, - "displayPrecisionEnumSet_endAt_13": {
- "title": "Display Precision",
- "$id": "#displayPrecisionEnumSet_endAt_13",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "displayPrecisionEnumSet.displayPrecisionPt000001",
- "title": "1000000ths",
- "memberId": 0
}
]
},
], - "setId": 0
}, - "restorePriorityEnumSet": {
- "title": "Restore Priority",
- "$id": "#restorePriorityEnumSet",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "restorePriorityEnumSet.7",
- "title": "Operator Override",
- "memberId": 7
}
]
},
], - "setId": 357
}, - "object-reference": {
- "$id": "#object-reference",
- "title": "Object reference data type",
- "type": "object",
- "properties": {
- "objectReference": {
- "format": "fully-qualified-reference",
- "type": "string"
}, - "referencedObject": {
- "type": "object",
- "properties": {
- "objectName": {
- "type": "string"
}, - "objectUrl": {
- "type": "string",
- "format": "uri"
}
}, - "readOnly": true
}
}
}, - "attribute-reference": {
- "$id": "#attribute-reference",
- "title": "Attribute reference data type",
- "allOf": [
- {
- "type": "object",
- "properties": {
- "attributeTitle": {
- "type": "string"
}, - "referencedObject": {
- "properties": {
- "attributeUrl": {
- "type": "string",
- "format": "uri"
}
}
}
}
}, - {
- "$ref": "#object-reference"
}
]
}, - "connectionDirectionSet_endAt_3": {
- "title": "Connection Value Direction",
- "$id": "#connectionDirectionSet_endAt_3",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "connectionDirectionSet.sendsValueTo",
- "title": "Sends Value To",
- "memberId": 0
}
]
},
], - "setId": 3102
}
}, - "required": [
- "name",
- "objectCategory",
- "prioritySupported",
- "minPresValue",
- "maxPresValue",
- "units",
- "displayPrecision",
- "covIncrement",
- "relinquishDefault",
- "restoreCommandPriority",
- "direction",
- "priorityForWritingToConnected"
]
}, - "views": [
- {
- "title": "Configuration",
- "views": [
- {
- "title": "Basic",
- "views": [
- {
- "title": "Object",
- "properties": [
- "name",
- "description",
- "bacnetObjectType",
- "objectCategory"
], - "id": "viewGroupEnumSet.objectGrp"
}, - {
- "title": "Engineering Values",
- "properties": [
- "prioritySupported",
- "minPresValue",
- "maxPresValue"
], - "id": "viewGroupEnumSet.engValuesGrp"
}, - {
- "title": "Display",
- "properties": [
- "units",
- "displayPrecision",
- "covIncrement"
], - "id": "viewGroupEnumSet.displayGrp"
}, - {
- "title": "Default State",
- "properties": [
- "relinquishDefault"
], - "id": "viewGroupEnumSet.defaultStateGrp"
}, - {
- "title": "Restart Options",
- "properties": [
- "restoreCommandPriority"
], - "id": "viewGroupEnumSet.restartOptionsGrp"
}, - {
- "title": "Connection Status",
- "properties": [
- "connectedTo",
- "direction",
- "priorityForWritingToConnected"
], - "id": "viewGroupEnumSet.connectionStatusGrp"
}
], - "id": "groupTypeEnumSet.basicGrpType"
}, - {
- "title": "Advanced",
- "views": [ ],
- "id": "groupTypeEnumSet.advancedGrpType"
}
], - "id": "viewNameEnumSet.configView"
}
]
}This operation is used to suggest values for identification properties for
the next object created in a specific location of a specific type. The
properties in question are name and localUniqueIdentifier. (The
localUniqueIdentifier isn't a true object property but it is a query
parameter used when creating an object and the value is used to generate the
itemReference property of an object.)
Note: there is no guarantee that the suggested values are still available at the time a client decides to use them to create a new object.
Note: For field controller objects, additional properties may also be
returned in addition to name and localUniqueIdentifier.
| objectType required | string Examples:
metasysEnum: objectTypeEnumSet The type of object The acceptable values for this parameter come from the See also:
|
| parentObjectId required | string Example: parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d An object ID that specifies the location in which a new object is intended to be created. The response payload will then contain identification values that are valid for that location. |
| extendedProperty | string Examples:
metasysEnum: attributeEnumSet The attribute to extend. Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions). The acceptable values for this parameter come from the See also:
|
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/schemas/objectTypes/objectTypeEnumSet.avClass/identification?parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d&extendedProperty=attributeEnumSet.presentValue' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This payload includes a schema that describes the name and localUniqueIdentifier properties and includes a default value for each. This default value for localUniqueIdentifier will always be unique for the given location at the time it is requested.
{- "schema": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "metasysType": "string",
- "default": "AV1",
- "maxLength": 400
}, - "localUniqueIdentifier": {
- "type": "string",
- "metasysType": "string",
- "default": "AV1",
- "maxLength": 32
}
}
}
}NOTE: The scope of this group of operations is under development and may change at any time.
This section describes the operations you can perform in the context of a site. A site represents a BAS installation at a given location, which may be a single building or multiple buildings. Use site operations to get a semantic model of the entire site.
Gets the explicit semantic knowledge facts of the site. A fact is an explicit statement, or RDF triple, that has been defined for the site.
In contrast, an inferred fact is a derived statement or piece of knowledge based on explicit facts and ontologies from which the explicit facts are associated to. Inferred facts of the site will not be included in the response of this operation. You will need to obtain the referenced ontologies from their available locations and apply your own set of inference rules in ways that are appropriate for your usage.
Note: The response to this operation may not reflect the latest state of the site if changes have recently been made or the site is actively undergoing changes. This operation will be delayed in providing the latest information until a sufficient quiet period has elapsed or active changes have occurred for a long period of time.
curl --request GET \ --url https://metasys-server.example.com/api/v5/site/rdf \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix data: <http://data.jci.com/data#> . @prefix jcb: <http://ontologies.jci.com/bacnetObjectModel#> . @prefix jc: <http://ontologies.jci.com/core#> . data:975b6588-2bca-5823-b3d6-4c0261b338e3 a jc:Supervisory_Controller; jcb:itemReference "{hostname}:{deviceHostname}"; rdfs:label "My Engine"; jcb:objectType 8; jcb:objectInstance 1 .
Retrieves the collection of spaces served by the specified network device. A space is served by a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/spaces?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}
], - "next": null,
- "previous": null,
}Retrieves the collection of spaces served by the specified equipment instance.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/spaces?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}
], - "next": null,
- "previous": null,
}Retrieves a collection of spaces.
| type | string Example: type=spaceTypesEnumSet.building metasysType: enum metasysEnum: spaceTypesEnumSet Type of space to return. The acceptable values for this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/spaces?type=spaceTypesEnumSet.building&page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}
], - "next": null,
- "previous": null,
}Retrieves the specified space.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}Retrieves the collection of spaces that are located within the specified space.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/spaces?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "ca8fbdbb-8e44-41fd-a765-da18de80a8f1",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building",
- "name": "Building",
- "type": "spaceTypesEnumSet.building",
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/ca8fbdbb-8e44-41fd-a765-da18de80a8f1/networkDevices"
}
], - "next": null,
- "previous": null,
}Operations for managing subscriptions to status information for network devices and trees.
Clients may subscribe to several different types of status information, including:
device summary is a high level overview of the entire site. It
provides a list of all non ok statuses occurring on each network
device, grouped by network device.
device details provides a list of all objects with non ok status for
a single network device of interest.
tree details provides a list of all objects with non ok status for a
single tree of interest.
The device summary is used by the Metasys User Interface (MUI) to overlay status indicators (icons) on the unexpanded Building Network tree. When a user expands a network device, MUI subscribes for device details for that device. The device details allow MUI to overlay status indicators on the child objects of that network device. When a user expands a different network device, three things happen:
This is an example of a well behaved client, because device details are not subscribed before they are needed and device details are unsubscribed when they are no longer needed.
Tree details is very similar to device details, except that the scope of the subscription is for a tree (formerly called "User Views" in the Site Management Portal).
Both device details and tree details employ the concepts of rank and
propagates. Rank is the severity of the status, with a higher rank
being more severe. When multiple statuses apply, Metasys user interfaces
show the one with the highest rank. Propagates is a hint as to how to
apply a status to the hierarchy. For example, if a field controller
connected to a network device goes offline
(objectStatusEnumSet.osOffline), then that status would be accompanied
with a hint to propagate down to all children of that field device
(propagates: down). These hints help the event message be succinct and
not have to include an entry for each child object. Propagation is up
for objectStatusEnumSet.osLowAlarm, to indicate there is some object in
an alarm state on this network device. And finally, sometimes there is no
propagation. Such is the case for objectStatusEnumSet.osInactive.
The following events (with accompanying examples) are available for status indicators:
statusIndicators.subscription.cancelled - Indicates when a
subscription has been cancelled by the system. The subscription has
removed and no more updates will arrive for this subscription. Try to
subscribe again, but if the problem persists, please contact to your
system administrator.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"]
}
statusIndicators.networkDeviceSummary.update - Indicates a change in
device summary status.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"items": [
// an "item" for each network device on the site
// note: due to Streaming event size limits, entire update may be split across multiple events
{
"id": "guid of device",
// Most severe non-OK status amongst all objects on the network device
// (excluding any offline field devices) or defaults to objectStatusEnumSet.osNormal.
"summarizedStatus": "objectStatusEnumSet.osLowAlarm",
// List of all non-OK statuses for objects on the network device
"objectStatuses": [
"objectStatusEnumSet.osOffline",
"objectStatusEnumSet.osLowAlarm",
"objectStatusEnumSet.osHighWarning",
"objectStatusEnumSet.osInactive"
]
}
]
}
statusIndicators.networkDeviceDetails.update - Indicates a change in
network device detail status.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"items": [
// an "item" for each supervisory device on the site
// note: due to Streaming event size limits, entire update may be split across multiple events
{
"id": "guid of device",
"objects": [
{
// one "object" for each non-OK object on the supervisory device
"id": "guid of object 1",
"objectStatus": "objectStatusEnumSet.osInactive",
"propagates": "none",
"rank": 1
},
{
"id": "guid of object 2",
"objectStatus": "objectStatusEnumSet.osLowAlarm",
"propagates": "up", // up: ancestor nodes
"rank": 30
},
{
"id": "guid of object 3",
"objectStatus": "objectStatusEnumSet.osOffline",
"propagates": "down", // down: child nodes
"rank": 112
}
]
}
]
}
statusIndicators.treeDetails.update - Indicates a change in tree
detail status.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"total": 2,
"items": [
// an "item" for each tree
// note: due to Streaming event size limits, entire update may be split across multiple events
{
"id": "guid of tree (user view)",
"objects": [
{
// one "object" for each non-OK object in the tree
"id": "guid of object 1",
"objectStatus": "objectStatusEnumSet.osInactive",
"propagates": "none",
"rank": 1
},
{
"id": "guid of object 2",
"objectStatus": "objectStatusEnumSet.osLowAlarm",
"propagates": "up", // up: ancestor nodes
"rank": 30
},
{
"id": "guid of object 3",
"objectStatus": "objectStatusEnumSet.osOffline",
"propagates": "none", // field controller offline doesn't propagate in user views
"rank": 112
}
]
}
]
}
statusIndicators.heartbeat - Affirms subscription(s) that are still
active.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"message": "ping from status indicator service @2021-08-04T16:03:23.3771485Z"
}
Create a subscription to network device summary, detailed status of network device(s) and detailed status of tree(s).
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
Used to convey the desired subscription.
| networkDeviceSummary | boolean Indicate if network device summary information is desired. |
| networkDeviceDetails | Array of strings Array of network device identifiers to subscribe for status details. |
| treeDetails | Array of strings Array of tree identifiers to subscribe for status details. |
{- "networkDeviceSummary": true,
- "networkDeviceDetails": [
- "e62509b0-bf40-49bd-a457-9775bc48e2af",
- "f62509b0-bf40-49bd-a457-9775bc48e2af"
], - "treeDetails": [
- "264ddedf-498c-49e6-bfb9-bc05544f7819"
]
}The request body contains an unrecognized network device id.
{- "statusName": "api:error.deviceNotFound",
- "message": "Could not find network device by ID.",
- "details": {
- "deviceId": "d9bf66bd-22f8-425b-82a4-44ba153d79c7"
}
}Modify a subscription to network device summary, detailed status of network device(s) and detailed status of tree(s).
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
Used to convey the desired subscription.
| networkDeviceSummary | boolean Indicate if network device summary information is desired. |
| networkDeviceDetails | Array of strings Array of network device identifiers to subscribe for status details. |
| treeDetails | Array of strings Array of tree identifiers to subscribe for status details. |
{- "networkDeviceSummary": true,
- "networkDeviceDetails": [
- "e62509b0-bf40-49bd-a457-9775bc48e2af",
- "f62509b0-bf40-49bd-a457-9775bc48e2af"
], - "treeDetails": [
- "264ddedf-498c-49e6-bfb9-bc05544f7819"
]
}The request body contains an unrecognized network device id.
{- "statusName": "api:error.deviceNotFound",
- "message": "Could not find network device by ID.",
- "details": {
- "deviceId": "d9bf66bd-22f8-425b-82a4-44ba153d79c7"
}
}Deletes a subscription to status indicators.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/statusIndicators/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Your Metasys system works continuously: sensors report current conditions, algorithms make adjustments, and alarms alert operators to potential issues. Streaming is how the Metasys API provides access to these events using the HTML standard server-sent events (SSE). For further information, refer to Mozilla developer guide. In this document, Streaming typically refers to the Metasys feature and stream refers to the concept of the HTTP connection and the flow of data.
Per the standard, a server-sent event usually contains three components, separated by newline, with the last component having a second newline to mark the end of the event.
id: <event id>\n
event: <event type>\n
data: <event data>\n\n
| Line Prefix | Explanation |
|---|---|
id |
ordering id to enable the "pick up where you left off" reconnection |
event |
message type |
data |
message payload as a JSON string |
Example:
id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:1\n
event: hello\n
data: b6d184ee-e137-44aa-b9b1-14bc704cd25d\n\n
To get started, you first need a client. There are SSE clients available in many languages.
Begin by getting a stream. Only one stream is needed
regardless of the number of subscriptions you later create. As explained in the
documentation for getting a stream, the first event, hello, is a special event
because the data field contains your stream ID.
Some operations support the METASYS-SUBSCRIBE header which transforms them
from being a single request/response operations into a streaming subscription.
The value of the header is the stream ID from the data field of the hello
event described above. As an example, refer to the
Get Activities operation for more details about this
technique. This technique does not apply to every operation. See each
operation's description to understand its Streaming capability.
Not all event data is currently exposed by Streaming. Future versions of the API will add further Streaming capabilities.
There are a few behaviors to be aware of if you want your stream to work beyond the lifetime of the access token used to get your stream.
Recall that your access token has an expiration time. To keep the stream longer than the lifetime of that access token, be sure to refresh your token just as you would when using non-Streaming portions of the API. Not only will you get a fresh token to use, but internally, your stream expirations are updated to match the expiration time of the new token.
The server-sent events standard has a provision for reconnecting a lost
connection. Call the same get a stream operation but
also add the Last-Event-Id header with the id of the last event received.
Most clients handle this for you. Metasys continues to buffer events for at
least thirty seconds after the connection failure is detected, so you can resume
streams that experienced brief outages. If Metasys has cleaned up your buffer or
cannot find that id in the recently sent buffer, you will get a 204 response
per the SSE specification. Because your existing stream is not resumable, your
Last-Event-Id is no longer valid. The recovery path is to start anew by
calling get a stream without the Last-Event-Id and
subscribe again to data of interest.
One critical aspect of reconnect is ensuring that the reconnect request is done
with the current access token. As covered by
get a stream, Streaming lets you specify the token in
either the Authorization header or query string. This flexibility accommodates
a variety of clients. For example, the web browser client, EventSource, does
not provide access to request headers, so you have to use the query string.
For EventSource, this however poses an issue because the reconnect attempt
will be done against the original URL which has a potentially outdated access
token embedded in the query string. For that reason, if you want to use a
JavaScript client, consider using the open source
EventSource component. The Metasys
User Interface (MUI) employs this library to workaround the limitation of the
browser's EventSource . When using it, use the Authorization header instead.
Keep the options object passed to the constructor so you can update the
Authorization property when you refresh your access token.
Assuming:
accessTokenstreamingUrl is the URL for get a streamconst eventSourceOptions = {
headers: {
Authorization: `Bearer ${accessToken}`,
},
};
const eventSource = new $window.EventSourcePolyfill(
streamingUrl,
eventSourceOptions
);
Before token expiration:
eventSourceOptions with new token like example beloweventSourceOptions.headers.Authorization = `Bearer ${newToken}`;
SSE clients exist in many languages. Inclusion in this section is not an endorsement; however, if you chose one of these clients, these tips may prove useful for ensuring the current token is used for reconnect.
When using the
3ventic EventSource for C# you will need
to use Reflection to update Uri which is a private field within the
EventSource that contains the location to get a stream
with the access token embedded in the query string.
public static void SetField(Object obj, String fieldName, object value)
{
Type type = obj.GetType();
FieldInfo field = type.GetField(
fieldName,
BindingFlags.NonPublic | BindingFlags.Instance
);
field.SetValue(obj, value);
}
// example usage
Reflector.SetField(eventSource, "Uri", uriWithCurrentToken);
When using the
LaunchDarkly EventSource for C#
you will not call the Reset method to attempt a reconnect. Instead, dispose of
the EventSource and then create a new instance, passing the the LastEventId
from the last message and the URL to get a stream with a
current access token embedded as a query string parameter.
The following are types of events sent by Streaming along with example data
payloads for each:
hello - Indicates Streaming connection was successful.
"b6d184ee-e137-44aa-b9b1-14bc704cd25d"
heartbeat - Indicates Streaming connection is alive.
"2021-02-16T16:21:10.23Z"
Opens or reconnects a Server Sent Event stream which is a prerequisite for subscribing to any dynamic updates
| Last-Event-Id | string Example: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5 Providing the ID of the last event received enables a briefly broken stream to be resumed |
curl --request GET \ --url https://metasys-server.example.com/api/v5/stream \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'Last-Event-Id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5'
Keep all streams associated to the user session alive and open without interruption until the new token expiration or closed by the client.
This is called internally by the various token refresh endpoints to simplify things for users. There is no need for a user to call this.
curl --request GET \ --url https://metasys-server.example.com/api/v5/stream/keepalive \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Retrieves some basic version and platform information of a site.
curl --request GET \ --url https://metasys-server.example.com/api/v5/system \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "about": {
- "copyright": {
- "holder": "Johnson Controls, Plc.",
- "years": [
- 2013,
- 2020
]
}, - "environment": {
- "platform": "server",
- "metasysHost": "{hostname}",
- "metasysSite": "My Site",
- "metasysVersion": "13.0.0.0"
}
},
}Returns a collection of key/value pairs that describe the capabilities of a site.
curl --request GET \ --url https://metasys-server.example.com/api/v5/system/capabilities \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": {
- "localization.user.locale": "",
- "localization.user.decimalSeparator": ".",
- "localization.user.thousandSeparator": ".",
- "localization.multipleLanguageSupport": true,
- "localization.defaultLanguage": true,
- "localization.locale": "[ 'cs-CZ', 'de-DE', 'es-ES', 'fr-FR', 'it-IT', 'nb-NO', 'nl-NL', 'pl-PL', 'pt-BR', 'ru-RU', 'sv-SE' ]",
- "application.limit.floatValue": 3.4082e+38,
- "application.limit.dateRangeInYear": 1,
- "application.limit.folderNameCharacterLength": 100,
- "application.message.fadeOutTimeInMilliseconds": 3000,
- "application.notificationManager.enabled": true,
- "application.dashboardManager.enabled": true,
- "application.offline.enabled": false,
- "api.timeoutInMilliseconds": 30000,
- "navigation.widthInPixel": 960,
- "diagnostic.log.enabled": false,
- "point.update.delayInMilliseconds": 1000,
- "object.management.deletePreviewLimit": 1000,
- "object.management.createBatchSize": 50,
- "object.management.discoveryPageSize": 1000,
- "object.discovery.selectionCount": 5000,
- "object.discovery.reloadTimeInMilliseconds": 5000,
- "object.controllerClass.discoveryEnabled": true,
- "object.annotation.enabled": false,
- "audits.annotation.enabled": true,
- "events.annotation.enabled": true,
- "analytics.enabled": true,
- "analytics.license.commercialTrackingId": "UA-119672247-5",
- "analytics.license.demoTrackingId": "UA-119672247-4",
- "analytics.license.graceTrackingId": "UA-119672247-3",
- "analytics.license.trialTrackingId": "UA-119672247-2",
- "analytics.license.technicianTrackingId": "UA-119672247-1",
- "network.batchSize": 250,
- "network.search.enabled": true,
- "network.item.selectionCount": 100,
- "network.email.maxAllowedRecipient": 10,
- "graphics.masterLayerEnabled": true,
- "graphics.servingEnabled": false,
- "graphics.symbolLibraryEnabled": true,
- "graphics.maxLayer": 15,
- "graphics.readFromBindingEnabled": true,
- "graphics.snappingStatusEnabled": true,
- "graphics.snapState": "snappingState",
- "graphics.autoSaveEnabled": true,
- "graphics.autoSaveState": "autoSaveState",
- "graphics.maxNameCharacterLength": 255,
- "graphics.customBehavior.enabled": true,
- "graphics.save.enabled": true,
- "graphics.save.intervalInSeconds": 120,
- "graphics.floor.enabled": true,
- "graphics.floor.editingEnabled": true,
- "graphics.manager.enabled": true,
- "graphics.import.enabled": false,
- "graphics.export.enabled": false,
- "graphics.editor.customBehaviorEnabled": true,
- "graphics.editor.customBehaviorEventEnabled": true,
- "graphics.editor.customSymbolImportEnabled": true,
- "graphics.editor.customSymbolExportEnabled": true,
- "report.historical.enabled": true,
- "report.schedule.enabled": true,
- "report.onTime.enabled": true,
- "report.trend.enabled": true,
- "report.predefined.enabled": true,
- "report.canned.enabled": true,
- "report.sync.maxDateRangeInYear": 5,
- "ppa.enabled": true,
- "ppa.desktopPageLimit": 25,
- "ppa.mobilePageLimit": 15,
- "fault.detectionEnabled": true,
- "fault.triageEnabled": true,
- "fault.url.manager": "/UI/FaultManager",
- "fault.url.triage": "/UI/FaultTriage",
- "fault.refreshButton.enableDurationInMinutes": 30,
- "fault.cutOff.rank.medium": 1000,
- "fault.cutOff.rank.high": 3000,
- "fault.cutOff.rank.critical": 6000,
- "fault.cutOff.severity.medium": 290,
- "fault.cutOff.severity.high": 540,
- "fault.cutOff.severity.critical": 930,
- "activeDirectory.enabled": true,
- "role.management.enabled": true,
- "user.management.enabled": true,
- "user.management.filter.role.maxSelection": 10,
- "user.management.filter.user.maxRoleSelection": 10,
- "user.management.grid.pageCount": 5,
- "user.management.grid.itemsPerPage": 25,
- "user.management.grid.spaceAuthorization.enabled": true,
- "user.management.filter.activeDirectoryUserType.enabled": true,
- "user.management.create.activeDirectoryUserType.enabled": true,
- "user.management.setupTab.enabled": true,
- "user.management.userViewTab.enabled": true,
- "user.notes.enabled": true,
- "user.notes.updateEnabled": false,
- "user.annotation.maxLength": 255,
- "annotation.enabled": true,
- "forcedAnnotation.enabled": true,
- "export.csv.enabled": true,
- "export.pdf.enabled": true,
- "equipment.enabled": true,
- "equipment.visiblePoint": 3,
- "equipment.visibleServingPoint": 2,
- "equipment.summary.columns": 8,
- "equipment.summary.pageOnDesktop": 25,
- "equipment.summary.pageOnMobile": 15,
- "equipment.activity.fetchMonthEnabled": true,
- "equipment.activity.monthHeaderBatch": 4,
- "equipment.activity.batchSize": 16,
- "equipment.servingSpace.maxLevel": 5,
- "equipment.servingSpace.maxPoint": 20,
- "equipment.relation.maxSpace": 30,
- "equipment.relation.maxServing": 200,
- "equipment.relation.maxServedBy": 10,
- "equipment.relation.maxController": 10,
- "alarm.announcement.enabled": true,
- "alarm.announcement.pageSize": 100,
- "alarm.audio.enabledOnMobile": true,
- "alarm.audio.enabledOnMonitor": true,
- "alarm.manager.enabled": true,
- "alarm.manager.popView": true,
- "alarm.manager.maxRecordOnMobile": 100,
- "alarm.manager.numberOfBarColumn": 6,
- "alarm.manager.maxRecord": 1000,
- "alarm.manager.occurrenceLimit": 10,
- "alarm.manager.maxOccurrence": 9999,
- "alarm.integration.enabled": false,
- "alarm.update.delayInMilliseconds": 1000,
- "alarm.monitor.enabled": true,
- "alarm.event.actionEnabled": true,
- "command.defaultHour": 4,
- "command.defaultMinute": 0,
- "command.annotation.enabled": true,
- "networkNavigation.userViewEnabled": true,
- "networkNavigation.allItemTreeEnabled": true,
- "networkNavigation.buildingNetwork.enabled": true,
- "networkNavigation.buildingNetwork.organized": true,
- "networkNavigation.buildingNetwork.treeEnabled": true,
- "networkNavigation.buildingNetwork.navTree.retrofitEnabled": false,
- "networkNavigation.buildingNetwork.siteDirector.minVersion": "10.0.0.0",
- "systemActivity.enabled": true,
- "systemActivity.gridMaxActivity": 10000,
- "systemActivity.pageSize": 1000,
- "systemActivity.events.enabled": true,
- "systemActivity.events.rollUp": true,
- "systemActivity.audits.enabled": true,
- "dashboard.cyberHealth.enabled": true,
- "dashboard.route.refresh.duringAlarmEnabled": false,
- "dashboard.route.refresh.limit": 200,
- "schedule.enabled": true,
- "schedule.editingEnabled": true,
- "schedule.mobileEditingEnabled": true,
- "schedule.firstUpdateSuppress": true,
- "schedule.eventsExceptionLimit": 32,
- "schedule.defaultScheduleType": "effective",
- "schedule.report.pagesize": 25,
- "schedule.report.timeoutInMilliseconds": 600000,
- "schedule.pageCount.onDesktop": 100,
- "schedule.pageCount.onMobile": 25,
- "schedule.summary.pageMaxSize": 20000,
- "summary.view.limitOnDesktop": 200,
- "summary.view.limitOnMobile": 50,
- "trend.enabled": true,
- "trend.studyManager.enabled": true,
- "trend.live.enabled": true,
- "trend.custom.enabled": true,
- "trend.custom.maxPoint": 32,
- "trend.pdf.orientationChangeLimit": 5,
- "trend.widget.maxPoint": 10,
- "trend.trendAble.maxMobilePoint": 4,
- "trend.trendAble.maxPoint": 10,
- "trend.equipment.visiblePoint": 2,
- "trend.dynamicStatusEnabled": true,
- "trend.desktopNavigatorEnabled": true,
- "trend.timeoutInMilliseconds": 60000,
- "trend.sample.retrieveEnabled": true,
- "trend.sample.retrieveMaxLimit": 50000,
- "trend aggregation.enabled": true,
- "space.enabled": true,
- "space.tree.enabled": true,
- "space.authorization.enabled": true,
- "space.authExpandCollapse.enabled": false,
- "space.totalSpace.flag": false,
- "space.saveTimeoutInMilliseconds": 1000000,
- "space.maxExpanded": 1200,
- "search.advanced.enabled": true,
- "search.advanced.dynamicDataLimit": 500,
- "search.advanced.maxResults.desktop": 2000,
- "search.advanced.maxResults.tablet": 50,
- "search.quick.enabled": true,
- "search.autocompleteResultLimit": 10,
- "search.resultPageLimit": 30,
- "search.maxResults": 2000,
- "settings.graphics.enabled": true,
- "settings.summary.enabled": true,
- "settings.display.enabled": true,
- "settings.alarm.enabled": true,
- "settings.annotation.enabled": true,
- "settings.forcedAnnotation.enabled": true,
- "settings.usageAnalytics.enabled": true,
- "settings.trend.enabled": true,
- "notification.email.enabled": true,
- "notification.printer.enabled": true,
- "notification.snmp.enabled": true,
- "notification.syslog.enabled": true,
- "notification.announcement.enabled": true,
- "notification.testDestination.enabled": true,
- "notification.alarmEscalation.enabled": true,
- "notification.tree.enabled": true,
- "commanding.enabled": true,
- "editor.logic.enabled": true,
- "objectInvolvement.enabled": true,
- "tailoredSummaries.enabled": true,
- "tailoredSummaries.summaryDefinition.enabled": true,
- "siteManagement.SiteDirectorPairNxE.enabled": true,
- "software.updateDetection.enabled": true,
- "license.expiryDetection.enabled": true,
- "adfs.enabled": true,
- "engine.technical.maxLimit": 1000,
- "engine.licensed.maxLimit": "",
- "fieldDevice.technical.maxLimit": false,
- "object.technical.maxLimit": "",
- "object.licensed.maxLimit": "",
- "historical.dataRetention": true,
- "logic.streaming.enabled": true,
- "certificateManagement.enabled": true,
- "certificateManagement.connectionRequired": false,
- "certificateManagement.supervisorPassthru.enabled": false,
- "certificateManagement.directConnect.enabled": false
}
}Returns a set of key/value pairs that describe various system wide settings.
| includeSchema | boolean Default: false Example: includeSchema=true Indicates whether the schema for the settings should be returned in the response. |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/system/settings?includeSchema=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "item": {
- "validation.signature.reasons": [
- {
- "token": "mve.review"
}, - {
- "token": "mve.approve"
}, - {
- "token": "mve.author"
}, - {
- "token": "mve.op.action"
}, - {
- "text": "My custom reason"
}
], - "validation.signatureAndReason.inclusion": "^.*$",
- "validation.signatureAndReason.exclusion": "^FieldController1\\..*$|^Controller2\\..*$",
- "validation.signatureAndReason.alarmThreshold": 140,
- "validation.signatureAndAnnotation.inclusion": "^$",
- "validation.signatureAndAnnotation.exclusion": "^$",
- "validation.signatureAndAnnotation.alarmThreshold": 140,
- "validation.validatedDevices": [
- "nae1",
- "nae2"
], - "annotations.predefinedOptions": [
- "Test annotation",
- "This is just a test",
- "Adding annotations"
], - "colors.statusColors.normalColor": "#101ec0",
- "colors.statusColors.outOfServiceColor": "#25285e",
- "colors.statusColors.overriddenColor": "#0e6fdb",
- "colors.statusColors.troubleWarningColor": "#ffff00",
- "colors.statusColors.offlineColor": "#d41414",
- "colors.statusColors.inaccessibleColor": "#b02a2a",
- "colors.statusColors.alarmColor": "#a96060",
- "colors.statusColors.aboveSetpointColor": "#bf005f",
- "colors.statusColors.belowSetpointColor": "#a1a1d6",
- "colors.statusColors.unoccupiedColor": "#969696",
- "graphics.symbols.fan.stoppedColor": "#c47f7f",
- "graphics.symbols.fan.runningColor": "#77c08f",
- "colors.stateColors": [
- "#ffffff",
- "#009933",
- "#ff0000",
- "#0000ff"
], - "colors.allOtherStatesColor": "#b70dab",
- "graphics.behaviors.flash.simpleSymbolFlash": false,
- "graphics.behaviors.flash.flashInterval": 1,
- "graphics.behaviors.flash.flashType": "alternateFlashColor",
- "graphics.behaviors.flash.alternateColor": "#ffffff",
- "graphics.behaviors.flash.flashRateInMilliseconds": 100,
- "alarms.audibleAlarm.intervalInSeconds": 60,
- "alarms.audibleAlarm.defaultsToSystemBeep": false,
- "alarms.translucentColorsEnabled": true,
- "alarms.priorityLevels": [
- {
- "priority": 78,
- "backgroundColor": "#0e0e09",
- "foregroundColor": "#a41463"
}, - {
- "priority": 80,
- "backgroundColor": "#2020c6",
- "foregroundColor": "#484e16"
}, - {
- "priority": 85,
- "backgroundColor": "#c62021",
- "foregroundColor": "#2f63d0"
}, - {
- "priority": 89,
- "backgroundColor": "#6eedd7",
- "foregroundColor": "#e29d0a"
}, - {
- "priority": 139,
- "backgroundColor": "#ffff33",
- "foregroundColor": "#2de4d8"
}, - {
- "priority": 255,
- "backgroundColor": "#ffff33",
- "foregroundColor": "#af1ab5"
}
], - "alarms.audibleAlarm.audioFiles": [
], - "system.serverTimeSyncInMinutes": 30,
- "search.globalSearch.maxResults": 2000,
- "printing.defaultPaperSize": 0,
- "display.view.defaultHideUnauthorizedCommand": false,
- "activities.newActivityDurationInMinutes": 14
}
}Updates one or more system settings.
| item required | any One or more system settings with appropriate values. |
This request body example will set two values of system settings.it sets graphics.behaviors.flash.flashType to alarmColor & graphics.behaviors.flash.flashRateInMilliseconds to 251
{- "item": [
- {
- "graphics.behaviors.flash.flashType": "alarmColor"
}, - {
- "graphics.behaviors.flash.flashRateInMilliseconds": 251
}
]
}Update an individual system setting.
| settingId required | string Examples:
One of the keys in the response payload returned by Get system settings. |
| item required | any A value appropriate for the specific setting. |
This request body example will set the value of a setting to
"alarmColor". This would be appropriate for a setting like
graphics.behaviors.flash.flashType.
{- "item": "alarmColor"
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Sync Engines
Note at 13.0, this command wasn't actually updated to be available at v5.
To invoke it you need to use v4.
| ids required | Array of strings |
{- "ids": [
- "5fea8952-7db2-5a2d-9330-ee7fd2ff98b3",
- "6a2236e5-a4d8-522a-9b4a-353e4ae24aee"
]
}This section describes the operations you can perform on time series sample data.
The Metasys system has two locations from which time series samples can be
retrieved. The first is from the trend or log object, itself. Each object on
the Metasys site whose responsibility is to generate samples will have its own
buffer to store them. When samples are retrieved from the objects endpoints,
they will be retrieved from their respective buffers. Time series operations
that work with a buffer will include "(buffer)" in their summary.
The second location is from the repository. As samples are collected in the
trend or log objects themselves, those objects (if configured and enabled)
have the ability to forward that information to a repository. The repository
is the location on the LAN (Local Area Network) that can receive and store
historical data from one to many Metasys sources. Samples retrieved from the
timeSeries endpoint are retrieved from the particular Metasys device's
repository. Time series operations that work with the repository will include
"(repository)" in their summary.
Clients may subscribe to Objects and Network Devices streaming events. A
subscription is established by providing a METASYS-SUBSCRIBE header on a GET
operation of the samples resource under either the objects resource paths.
The following events (with accompanying examples) are available for samples:
timeSeries.subscription.established - Indicates when a subscription has been
established for objects samples.| subscriptionIds required | Array of strings List of all active subscriptionIds for this stream |
| message required | string The display string message that indicates that the subscription has been established successfully. |
required | Array of objects The collection of available items. |
| total required | integer The total number of items in the collection |
{- "subscriptionIds": [
- "7bd86189-3129-4463-841d-b2ad598fa4fd"
], - "message": "Sample subscription successful",
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "sampledObjects": [
- {
- "sampledObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "attribute": "presentValue",
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "sampledByObjectId": {
- "type": "string"
}, - "sampledObjectId": {
- "type": "string"
}, - "attribute": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}, - "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.noUnits",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}
}
]
}
], - "total": 1
}timeSeries.subscription.cancelled - Indicates when a subscription has been
cancelled for objects samples.| subscriptionIds required | Array of strings List of all subscriptionIds for this stream which have been cancelled. |
| message required | string The display string message that correlates to the subscriptions that have been cancelled. |
{- "subscriptionIds": [
- "b287344d-2d57-45c1-a9f2-1ec954a36984"
], - "message": "Sample subscription cancelled"
}timeSeries.error - Indicates an error occurred with regards to an active
samples subscription.| subscriptionIds required | Array of strings List of all subscription Ids for this stream for whom errors have been generated. |
| message required | string The display string message that provides information about the errors that have been generated. |
required | Array of objects The collection of available error items. |
| total required | integer The total number of items in the collection |
{- "subscriptionIds": [
- "68edbb25-00f0-4bcf-8008-235eab1d7bbc"
], - "message": "There was an issue in retrieving samples",
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "code": "api:error.internalFault",
- "message": "The endpoint encountered an internal fault"
}
], - "total": 1
}timeSeries.samples.update - Indicates new samples have been generated.
Sample updates from multiple objects and attributes can be contained in a
single event (each designated by their sampledByObjectId, sampledObjectId
and attribute properties).| subscriptionIds required | Array of strings List of all subscription IDs that the updates apply to for this stream |
| total required | integer The total number of items in the collection |
required | Array of objects A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to. |
{- "subscriptionIds": [
- "b287344d-2d57-45c1-a9f2-1ec954a36984"
], - "total": 2,
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "sampledObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "attribute": "presentValue",
- "value": -10,
- "sampleTime": "2023-05-05T10:07:00Z",
- "reliability": "reliabilityEnumSet.reliable"
}, - {
- "sampledByObjectId": "20a2fd2c-168f-502c-8221-db862d866402",
- "sampledObjectId": "831147e1-8dc7-5aa9-ac92-541fce8ab7b5",
- "attribute": "presentValue",
- "value": "binarypvEnumSet.bacbinInactive",
- "sampleTime": "2023-05-05T18:24:00Z",
- "reliability": "reliabilityEnumSet.reliable"
}
]
}timeSeries.heartbeat - Indicates that time series subscription(s) are still
alive.| currentTime required | string <date-time> Current server time in ISO8601 format |
| subscriptionIds required | Array of strings List of all active subscriptionIds for this stream |
{- "currentTime": "2022-01-01T00:00:00Z",
- "subscriptionIds": [
- "34a22b98-9bfc-41d3-a275-933e5977c447"
]
}Clients may subscribe to Objects Samples Response streaming events. A
subscription is established by providing a METASYS-CALL-ASYNC header on a
GET operation of the samples resource under either the objects resource
paths or POST operation of the samples resource under batch operation of
times buffer. The following events (with accompanying examples) are available
for samples:
The following events (with accompanying examples) are available for async samples:
timeSeries.samples.stream.started - Indicates when a subscription has been
established for objects samples response.| subscriptionIds required | Array of strings List of all active subscriptionIds for this stream |
| message required | string The display string message that indicates that the subscription has been established successfully. |
required | Array of objects The collection of available items. |
| total required | integer The total number of items in the collection |
{- "subscriptionIds": [
- "7bd86189-3129-4463-841d-b2ad598fa4fd"
], - "message": "Sample subscription successful",
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "sampledObjects": [
- {
- "sampledObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "attribute": "presentValue",
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "sampledByObjectId": {
- "type": "string"
}, - "sampledObjectId": {
- "type": "string"
}, - "attribute": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}, - "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.noUnits",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}
}
]
}
], - "total": 1
}timeSeries.samples.stream.error - Indicates an error occurred with regards
to an active samples response subscription.| subscriptionIds required | Array of strings List of all subscriptionIds for this async stream which an error has been generated, |
| message required | string The display string message that correlates to an error has occurred in async stream. |
{- "subscriptionIds": [
- "9c50fe10-a958-4bd4-b29f-0c4ac82c74bb"
], - "message": "An error occurred while streaming samples."
}timeSeries.samples.stream.data - Indicates samples responses for each
request. Samples from multiple objects and attributes can be contained in a
single event (each designated by their sampledByObjectId, sampledObjectId
and attribute properties).| subscriptionIds required | Array of strings List of all subscription IDs that the updates apply to for this stream |
| total required | integer The total number of items in the collection |
required | Array of objects A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to. |
{- "subscriptionIds": [
- "b287344d-2d57-45c1-a9f2-1ec954a36984"
], - "total": 2,
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "sampledObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "attribute": "presentValue",
- "value": -10,
- "sampleTime": "2023-05-05T10:07:00Z",
- "reliability": "reliabilityEnumSet.reliable"
}, - {
- "sampledByObjectId": "20a2fd2c-168f-502c-8221-db862d866402",
- "sampledObjectId": "831147e1-8dc7-5aa9-ac92-541fce8ab7b5",
- "attribute": "presentValue",
- "value": "binarypvEnumSet.bacbinInactive",
- "sampleTime": "2023-05-05T18:24:00Z",
- "reliability": "reliabilityEnumSet.reliable"
}
]
}timeSeries.samples.stream.completed - Indicates that a streaming samples
response has completed successfully.| subscriptionIds required | Array of strings List of all subscriptionIds for this async stream which has been completed. |
| message required | string The display string message that correlates to the completion of an async samples response. |
{- "subscriptionIds": [
- "9c50fe10-a958-4bd4-b29f-0c4ac82c74bb"
], - "message": "Samples stream response completed"
}The operation retrieves a collection of resources for which historical time series data exists. This operation uses the time series repository as its source of truth. It may contain data for objects that no longer actually exist on the site. This operation never considers time series that exist exclusively in buffers on devices and that are not configured to forward their samples to the repository.
| searchString | string Examples:
Filter results by finding objects with an |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 2000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "itemReference" Enum: "itemReference" "-itemReference" Example: sort=itemReference The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/timeSeries?searchString=AV&page=1&pageSize=100&sort=itemReference' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 2,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": "c82d160b-884c-5eac-bad4-89754f0069e0",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "name": "AV2",
- "sampledAttributes": [
- {
- "attribute": "attributeEnumSet.presentValue"
}
]
}, - {
- "id": "0e59b020-4b6d-5498-8c56-82d95709c5a7",
- "itemReference": "{hostname}:{deviceHostname}/Programming.AV3",
- "name": "AV3",
- "sampledAttributes": [
- {
- "attribute": "attributeEnumSet.presentValue"
}
]
}
],
}Retrieves a collection of attributes under the specified object for which samples are available in their respective local sample buffers.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get objects trended attributes response.
{- "total": 2,
- "items": [
- {
- "attribute": "attributeEnumSet.presentValue",
- "attributeSchema": {
- "type": "number",
- "metasysType": "float"
}, - "sampledBy": [
- {
- "item": {
- "id": "0fae85ad-9d37-471d-acf2-b9c196dce3c2",
- "itemReference": "{hostname}:{deviceHostname}/programming.meter1.trend1",
- "name": "Meter Pricing Window Sample",
- "enable": true
}
}, - {
- "item": {
- "id": "111a4a42-d506-4c98-93b8-42a1243c8c23",
- "itemReference": "{hostname}:{deviceHostname}/programming.meter1.trend2",
- "name": "Meter CoV Sample",
- "enable": false
}
}
]
}, - {
- "attribute": "attributeEnumSet.outOfService",
- "attributeSchema": {
- "type": "boolean",
- "metasysType": "bool"
}, - "sampledBy": [
- {
- "item": {
- "id": "4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7",
- "itemReference": "{hostname}:{deviceHostname}/programming.meter1.trend3",
- "name": "Trend - Out Of Service",
- "enable": true
}
}
]
}
],
}Retrieves a collection of attributes for the specified object for which samples are available in the trend repository.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get trended attributes from the trend repository response.
{- "total": 2,
- "items": [
- {
- "attribute": "attributeEnumSet.memoryUsage",
- "attributeSchema": {
- "type": "number",
- "metasysType": "float"
}
}, - {
- "attribute": "attributeEnumSet.alarmRate",
- "attributeSchema": {
- "type": "number",
- "metasysType": "ulong"
}
}
],
}Retrieves a collection of samples from the object's local sample buffer for the specified object attribute during a particular date and time range.
If the METASYS-SUBSCRIBE header is provided, then an event subscription
will be created which will include the events described in
Time Series.
Note: The parent endpoint
/objects/{objectId}/trendedAttributes/{attributeId} is not currently
supported.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| attributeId required | string Example: presentValue metasysType: enum metasysEnum: attributeEnumSet The identifier of the attribute. The acceptable values for this parameter come from the See also:
|
| startSampleTime | string <date-time> Example: startSampleTime=2020-05-12T16:46:47Z The date and time representing the earliest sample to return. |
| endSampleTime | string <date-time> Example: endSampleTime=2021-01-19T18:13:58.007Z The date and time representing the latest sample to return. |
| sort | string Default: "-sampleTime" Enum: "sampleTime" "-sampleTime" Example: sort=sampleTime The criteria to use when sorting results (see rules). |
| sampledById | Array of strings Examples:
Filter samples by objects by supplying one or more An attribute may have multiple objects sampling it. Use this parameter to include samples only from a specific object or set of objects. If no value is given for this parameter, then the response will contain samples from all of the objects sampling this attribute. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime&sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get samples from trend object response containing only analog values.
{- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue",
}Retrieves a collection of samples from the trend repository for the
specified object attribute during a particular date and time range. Note:
The parent endpoint
/timeSeries/{objectId}/trendedAttributes/{attributeId} is not currently
supported.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| attributeId required | string Example: presentValue metasysType: enum metasysEnum: attributeEnumSet The identifier of the attribute. The acceptable values for this parameter come from the See also:
|
| startSampleTime | string <date-time> Example: startSampleTime=2020-05-12T16:46:47Z The date and time representing the earliest sample to return. |
| endSampleTime | string <date-time> Example: endSampleTime=2021-01-19T18:13:58.007Z The date and time representing the latest sample to return. |
| page | integer >= 1 Default: 1 Example: page=5 The page of the collection being requested. |
| pageSize | integer <= 20000 Default: 500 Example: pageSize=500 The requested number of items in the response. |
| sort | string Default: "-sampleTime" Enum: "sampleTime" "-sampleTime" Example: sort=sampleTime The criteria to use when sorting results. Please refer to default sorting rules for general guidelines. |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&page=5&pageSize=500&sort=sampleTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get samples from the trend repository response containing only analog values.
{- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue",
}Retrieves a collection of samples from the trend object's local sample
buffer for a specific time range. This operation only applies to trend
objects which are objects that have an objectType of trendLogClass,
trendMapperClass, bacnetTrendLogExtClass, trendLogNoextensionClass,
bacnetTrendLogClass or bacnetTrendLogMultipleClass.
If the METASYS-SUBSCRIBE header is provided, then an event subscription
will be created which will include the events described in
Time Series.
If the METASYS-CALL-ASYNC header is provided, then an event subscription
will be created and the API response will be streamed through events
described in Time Series.
Note: This differs from Get attribute samples (buffer) which fetches
the samples for a specific attribute of an object. Get attribute samples
can be called on any object that has one or more trended attributes.
However this call is only applicable to trend objects as defined above.
| trendObjectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of a trend object. The specified object must have an |
| startSampleTime | string <date-time> Example: startSampleTime=2020-05-12T16:46:47Z The date and time representing the earliest sample to return. |
| endSampleTime | string <date-time> Example: endSampleTime=2021-01-19T18:13:58.007Z The date and time representing the latest sample to return. |
| sort | string Default: "-sampleTime" Enum: "sampleTime" "-sampleTime" Example: sort=sampleTime The criteria to use when sorting results. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
| METASYS-CALL-ASYNC | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b visibility: private (PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response. See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-CALL-ASYNC: 40e47e37-0f24-4101-8e1d-de96af4b648b' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
This example shows a response to a request to get samples from a BACnet Trend Log Multiple object. The object has two Input References. One of the references is to an analog value and the other is to an enum value.
{- "sampledObjects": [
- {
- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue",
}, - {
- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": "offOnSet.ooOn",
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.reliability",
}
],
}Retrieves a collection of attributes under the specified network device for which samples are available in their respective local sample buffer.
| id required | string Example: 6b092d2e-c795-4e90-95e8-5acafc74f19d The identifier of the network device. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/networkDevices/6b092d2e-c795-4e90-95e8-5acafc74f19d/trendedAttributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get network devices trended attributes response.
{- "total": 2,
- "items": [
- {
- "attribute": "attributeEnumSet.presentValue",
- "attributeSchema": {
- "type": "number",
- "metasysType": "float"
}, - "sampledBy": [
- {
- "item": {
- "id": "0fae85ad-9d37-471d-acf2-b9c196dce3c2",
- "itemReference": "{hostname}:{deviceHostname}/programming.meter1.trend1",
- "name": "Meter Pricing Window Sample",
- "enable": true
}
}, - {
- "item": {
- "id": "111a4a42-d506-4c98-93b8-42a1243c8c23",
- "itemReference": "{hostname}:{deviceHostname}/programming.meter1.trend2",
- "name": "Meter CoV Sample",
- "enable": false
}
}
]
}, - {
- "attribute": "attributeEnumSet.outOfService",
- "attributeSchema": {
- "type": "boolean",
- "metasysType": "bool"
}, - "sampledBy": [
- {
- "item": {
- "id": "4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7",
- "itemReference": "{hostname}:{deviceHostname}/programming.meter1.trend3",
- "name": "Trend - Out Of Service",
- "enable": true
}
}
]
}
],
}Retrieves a collection of samples from the network device's local sample buffer for the specified network device attribute during a particular date and time range.
If the METASYS-SUBSCRIBE header is provided, then an event subscription
will be created which will include the events described in
Time Series.
Note: The parent endpoint
/networkDevices/{id}/trendedAttributes/{attributeId} is not currently
supported.
| id required | string Example: c550095d-ee4c-4314-b415-b0577e383ee9 The identifier of the network device. |
| attributeId required | string Example: presentValue metasysType: enum metasysEnum: attributeEnumSet The identifier of the attribute. The acceptable values for this parameter come from the See also:
|
| startSampleTime | string <date-time> Example: startSampleTime=2020-05-12T16:46:47Z The date and time representing the earliest sample to return. |
| endSampleTime | string <date-time> Example: endSampleTime=2021-01-19T18:13:58.007Z The date and time representing the latest sample to return. |
| sort | string Default: "-sampleTime" Enum: "sampleTime" "-sampleTime" Example: sort=sampleTime The criteria to use when sorting results. |
| sampledById | Array of strings Examples:
Filter samples by objects by supplying one or more An attribute may have multiple objects sampling it. Use this parameter to include samples only from a specific object or set of objects. If no value is given for this parameter, then the response will contain samples from all of the objects sampling this attribute. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/networkDevices/c550095d-ee4c-4314-b415-b0577e383ee9/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime&sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get samples from trend object response containing only analog values.
{- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue",
}This operation is used to invoke multiple time series operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request. In this version of the API, the only time series related operations that can be used in this batch API are List object trended attributes (buffer), Get attribute samples (buffer) and Get object samples (buffer). This request is for fetching buffer data (as opposed to fetching data from the repository).
If the METASYS-CALL-ASYNC header is provided, then an event subscription
will be created and the API response will be streamed through events
described in Time Series.
| METASYS-CALL-ASYNC | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b visibility: private (PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response. See also: |
| method required | string Value: "GET" The HTTP method to use for each request. This property is
restricted to |
required | Array of objects (Request object) non-empty A collection of entries that represent the operations to invoke. |
This example shows a request body that will read samples for the
presentValue and enabled attributes for object
960534d2-7df5-5ed8-884c-164e7a2f280a and for the
presentValue attribute of object
c82d160b-884c-5eac-bad4-89754f0069e0.
{- "method": "GET",
- "requests": [
- {
- "id": "1",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/trendedAttributes/presentValue/samples"
}, - {
- "id": "2",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/trendedAttributes/enabled/samples?startSampleTime=2021-05-23T04:39:01.545Z&endSampleTime=2021-05-24T04:39:01.545Z&sort=-sampleTime&sampledById={trendExtensionId}"
}, - {
- "id": "3",
- "relativeUrl": "c82d160b-884c-5eac-bad4-89754f0069e0/trendedAttributes/presentValue/samples"
}
]
}The response to a batch request to fetch samples for three different attributes.
{- "responses": [
- {
- "id": "1",
- "status": 200,
- "body": {
- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue"
}
}, - {
- "id": "2",
- "status": 200,
- "body": {
- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "boolean",
- "metasysType": "bool"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": true,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.outOfService"
}
}, - {
- "id": "3",
- "status": 404,
- "body": {
- "code": "api:error.objectDeleted",
- "message": "The requested object could not be found or has been deleted"
}
}
]
}This operation is used to invoke multiple time series operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request. In this version of the API, the only time series related operations that can be used in this batch API are Get object samples (repository). This request is for fetching repository data (as opposed to fetching data from the buffer).
| method required | string Value: "GET" The HTTP method to use for each request. This property is
restricted to |
required | Array of objects (Request object) non-empty A collection of entries that represent the operations to invoke. |
This example shows a request body that will read samples for the
presentValue and enabled attributes for object
c550095d-ee4c-4314-b415-b0577e383ee9 and for the
presentValue attribute of object
c82d160b-884c-5eac-bad4-89754f0069e0.
{- "method": "GET",
- "requests": [
- {
- "id": "1",
- "relativeUrl": "c550095d-ee4c-4314-b415-b0577e383ee9/trendedAttributes/presentValue/samples"
}, - {
- "id": "2",
- "relativeUrl": "c550095d-ee4c-4314-b415-b0577e383ee9/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16:46:47.000Z&endSampleTime=2021-01-19T18:13:58.007Z&pageSize=1&page=2&sort=-sampleTime"
}, - {
- "id": "3",
- "relativeUrl": "c82d160b-884c-5eac-bad4-89754f0069e0/trendedAttributes/presentValue/samples"
}
]
}The response to a batch request to fetch samples for three different attributes.
{- "responses": [
- {
- "id": "1",
- "status": 200,
- "body": {
- "total": 21869,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1",
- "units": "unitEnumSet.noUnits"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
}, - {
- "$ref": "/schemas/enums/reliabilityEnumSet"
}
]
}
}
}
}, - "items": [
- {
- "value": 0,
- "sampleTime": "2022-05-18T04:38:10Z",
- "reliability": "reliabilityEnumSet.reliable"
}, - {
- "value": 0,
- "sampleTime": "2022-05-17T11:16:03Z",
- "reliability": "reliabilityEnumSet.reliable"
}
], - "attribute": "attributeEnumSet.presentValue",
- "previous": null,
}
}, - {
- "id": "2",
- "status": 200,
- "body": {
- "total": 0,
- "schema": null,
- "items": [ ],
- "attribute": "attributeEnumSet.presentValue",
- "next": null,
- "previous": null,
}
}, - {
- "id": "3",
- "status": 404,
- "body": {
- "code": "invalidObjectId",
- "message": "The requested objectId does not exist"
}
}
]
}Creates a subscription to trend buffer samples
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
New streaming subscription for time series data.
Array of objects Collection of items to sign up for. |
{- "items": [
- {
- "objectId": "c550095d-ee4c-4314-b415-b0577e383ee9",
- "attributeId": "presentValue"
}, - {
- "objectId": "c550095d-ee4c-4314-b415-b0577e383ee9",
- "attributeId": "reliability",
- "sampledById": [
- "4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7"
]
}, - {
- "objectId": "4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7"
}
]
}Replaces an existing subscription to trend buffer samples.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
Streaming subscription for time series data.
Array of objects Collection of items to sign up for. |
{- "items": [
- {
- "objectId": "c550095d-ee4c-4314-b415-b0577e383ee9",
- "attributeId": "presentValue"
}, - {
- "objectId": "c550095d-ee4c-4314-b415-b0577e383ee9",
- "attributeId": "reliability",
- "sampledById": [
- "4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7"
]
}, - {
- "objectId": "4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7"
}
]
}Deletes a subscription to trend samples.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https://metasys-server.example.com/api/v5/timeSeries/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Retrieves a list of users for the well-known user status query. Status information in the query includes account status and dormancy details to provide an overview of user activity on the system.
Note: At this release, this operation is only supported when the
networkDeviceId is for the site director device.
| networkDeviceId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the network device object for a well known query. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/networkDevices/5a22812f-ec51-4c11-ab4a-fc986f94f008/wellKnownQueries/userStatus \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get all users on the device with their status, including dormancy of each account based on activity.
{- "items": [
- {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "Y3dldGhlcmlsbDA",
- "username": "cwetherill0",
- "fullName": "Corby Wetherill",
- "roles": [
- "ADMINISTRATOR"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2021-10-03T15:58:45Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P30D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "YmJyYWRsYXVnaDE",
- "username": "bbradlaugh1",
- "fullName": "Bobbye Bradlaugh",
- "roles": [
- "ADMINISTRATOR"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2021-10-07T07:37:49Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P30D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "aWtvcm5pbHlldjI",
- "username": "ikornilyev2",
- "fullName": "Ignacio Kornilyev",
- "roles": [
- "ADMINISTRATOR",
- "USER"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2022-02-11T14:29:05Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusYes",
- "dormantDuration": "P4D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusYes"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "Z3BpY2tlcnNhaWwz",
- "username": "gpickersail3",
- "fullName": "Grazia Pickersail",
- "roles": [
- "OPERATOR"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2022-04-03T08:35:10Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P30D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "cm1hbGFmZTQ",
- "username": "rmalafe4",
- "fullName": "Rosie Malafe",
- "roles": [
- "OPERATOR"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2021-10-08T14:56:40Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P5D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "Y29zZ29yYnk1",
- "username": "cosgorby5",
- "fullName": "Christalle Osgorby",
- "roles": [
- "ADMINISTRATOR",
- "USER"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2021-08-11T13:42:42Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P30D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "ZHBhc3NsZXI2",
- "username": "dpassler6",
- "fullName": "Del Passler",
- "roles": [
- "USER"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2021-11-18T14:11:39Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P30D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "ZHZhbnl1c2hraW43",
- "username": "dvanyushkin7",
- "fullName": "Dorelia Vanyushkin",
- "roles": [
- "ADMINISTRATOR",
- "USER"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2021-08-16T10:11:04Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P20D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "a3N3ZXBzdG9uZTg",
- "username": "kswepstone8",
- "fullName": "Kassey Swepstone",
- "roles": [
- "ADMINISTRATOR"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2022-03-03T23:58:25Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P1D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}, - {
- "networkDeviceId": "01c6be87-613b-44df-b72a-8c977e8e3722",
- "networkDeviceReference": "{hostname}:{deviceHostname}",
- "userId": "YnR1bnNsZXk5",
- "username": "btunsley9",
- "fullName": "Barbara-anne Tunsley",
- "roles": [
- "ADMINISTRATOR",
- "USER"
], - "authenticationType": "metasysAccountTypeEnumSet.accountTypeLocal",
- "lastSuccessfulLoginDate": "2021-10-17T00:45:03Z",
- "accountStatus": "dormantUserAccountStatusEnumSet.accountStatusActive",
- "dormantStatus": "dormantStatusEnumSet.dormantStatusNo",
- "dormantDuration": "P10D",
- "dormantAlarmCreated": "dormantStatusEnumSet.dormantStatusNo"
}
]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Retrieves a collection of users.
| roles | Array of strings Example: roles=USER&roles=OPERATOR |
| userLastLoggedinAfter | string <date-time> Example: userLastLoggedinAfter=2022-08-05T05:00:00Z Only include users that have logged in after this date-time. |
| userLastLoggedinBefore | string <date-time> Example: userLastLoggedinBefore=2022-08-05T05:00:00Z Only include users that have logged in before this date-time. |
| excludeMetasysUsers | boolean Default: false Example: excludeMetasysUsers=true Indicates if metasys (local) user accounts should be excluded from the results. Note: You will get a |
| excludeRadiusUsers | boolean Default: false Example: excludeRadiusUsers=true Indicates if RADIUS user accounts should be excluded from the results. |
| excludeADUsers | boolean Default: false Example: excludeADUsers=true Indicates if active directory user accounts should be excluded from the results. |
| q | string Example: q=true A search string used to filter results. At a minimum |
| page | integer Default: 1 Example: page=3 Results are returned in paged collections. This parameter specifies which page to return. |
| pageSize | integer Default: 100 Example: pageSize=50 Results are returned in paged collections. This parameter specifies how many results to include per page. |
| sort | string Default: "userName" Enum: "fullName" "-fullName" "lastLogin" "-lastLogin" "primaryEmail" "-primaryEmail" "userName" "-userName" Example: sort=userName The criteria to use when sorting results (see rules). |
| format | string Enum: "pdf" "csv" Example: format=csv The normal response is JSON. Use the |
curl --request GET \ --url 'https://metasys-server.example.com/api/v5/users?roles=USER&roles=OPERATOR&userLastLoggedinAfter=2022-08-05T05%3A00%3A00Z&userLastLoggedinBefore=2022-08-05T05%3A00%3A00Z&excludeMetasysUsers=true&excludeRadiusUsers=true&excludeADUsers=true&q=true&page=3&pageSize=50&sort=userName&format=csv' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 185,
- "previous": null,
- "items": [
- {
- "id": "Z3JlZ2M",
- "description": "",
- "primaryPhone": "",
- "locale": "US",
- "language": "en",
- "totalRoles": 2,
- "accessType": "Standard",
- "isAudibleAlarmEnabled": false,
- "userDefined": true,
- "userName": "gregc",
- "fullName": "",
- "primaryEmail": "",
- "roles": [
- {
- "id": "QURNSU5JU1RSQVRPUg",
- "roleName": "ADMINISTRATOR"
}, - {
- "id": "VVNFUg",
- "roleName": "USER"
}
], - "authenticationType": "metasys",
- "lastLogin": "2022-07-18T16:14:04Z",
- "accountStatus": [
- "Active"
]
}, - {
- "id": "amVzc2ljYQ",
- "description": "",
- "primaryPhone": "",
- "locale": "US",
- "language": "en",
- "totalRoles": 2,
- "accessType": "Standard",
- "isAudibleAlarmEnabled": false,
- "userDefined": true,
- "userName": "jessica",
- "fullName": "",
- "primaryEmail": "",
- "roles": [
- {
- "id": "QURNSU5JU1RSQVRPUg",
- "roleName": "ADMINISTRATOR"
}, - {
- "id": "VVNFUg",
- "roleName": "USER"
}
], - "authenticationType": "metasys",
- "lastLogin": "2022-08-05T14:21:32Z",
- "accountStatus": [
- "Active"
]
}
], - "pageNumber": 1
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Retrieves a specific user account.
This operation requires admin privileges.
| userId required | string Example: anNtaXRo The identifier of the user to retrieve. |
curl --request GET \ --url https://metasys-server.example.com/api/v5/users/anNtaXRo \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "userName": "jsmith",
- "profile": {
- "id": "anNtaXRo",
- "description": "",
- "primaryPhone": "",
- "locale": "US",
- "language": "en",
- "totalRoles": null,
- "roles": null,
- "accessType": null,
- "isAudibleAlarmEnabled": true,
- "userDefined": true,
- "userName": "jsmith",
- "fullName": "",
- "primaryEmail": "",
- "authenticationType": "metasys",
- "lastLogin": null,
- "accountStatus": null
}, - "permissions": {
- "id": "anNtaXRo",
- "userName": "jsmith",
- "userType": null,
- "userPermissions": { },
- "rolePermissions": {
- "hvac": [
- "fullAccess"
], - "fire": [
- "fullAccess"
], - "security": [
- "fullAccess"
], - "services": [
- "fullAccess"
], - "administrative": [
- "fullAccess"
], - "general": [
- "fullAccess"
], - "lighting": [
- "fullAccess"
], - "refrigeration": [
- "fullAccess"
], - "criticalEnvironment": [
- "fullAccess"
], - "airQuality": [
- "fullAccess"
], - "power": [
- "fullAccess"
], - "energy": [
- "fullAccess"
], - "system": [
- "fullAccess"
], - "custom1": [
- "fullAccess"
], - "custom2": [
- "fullAccess"
], - "custom3": [
- "fullAccess"
], - "custom4": [
- "fullAccess"
], - "custom5": [
- "fullAccess"
], - "custom6": [
- "fullAccess"
], - "custom7": [
- "fullAccess"
], - "custom8": [
- "fullAccess"
], - "custom9": [
- "fullAccess"
], - "custom10": [
- "fullAccess"
], - "custom11": [
- "fullAccess"
], - "custom12": [
- "fullAccess"
], - "custom13": [
- "fullAccess"
], - "custom14": [
- "fullAccess"
], - "custom15": [
- "fullAccess"
], - "custom16": [
- "fullAccess"
], - "custom17": [
- "fullAccess"
], - "custom18": [
- "fullAccess"
], - "custom19": [
- "fullAccess"
], - "custom20": [
- "fullAccess"
], - "custom21": [
- "fullAccess"
], - "custom22": [
- "fullAccess"
], - "custom23": [
- "fullAccess"
], - "custom24": [
- "fullAccess"
], - "custom25": [
- "fullAccess"
], - "custom26": [
- "fullAccess"
], - "custom27": [
- "fullAccess"
], - "custom28": [
- "fullAccess"
], - "custom29": [
- "fullAccess"
], - "custom30": [
- "fullAccess"
], - "custom31": [
- "fullAccess"
], - "custom32": [
- "fullAccess"
], - "custom33": [
- "fullAccess"
], - "custom34": [
- "fullAccess"
], - "custom35": [
- "fullAccess"
], - "custom36": [
- "fullAccess"
], - "custom37": [
- "fullAccess"
], - "custom38": [
- "fullAccess"
], - "custom39": [
- "fullAccess"
], - "custom40": [
- "fullAccess"
], - "custom41": [
- "fullAccess"
], - "custom42": [
- "fullAccess"
], - "custom43": [
- "fullAccess"
], - "custom44": [
- "fullAccess"
], - "custom45": [
- "fullAccess"
], - "custom46": [
- "fullAccess"
], - "custom47": [
- "fullAccess"
], - "custom48": [
- "fullAccess"
], - "custom49": [
- "fullAccess"
], - "custom50": [
- "fullAccess"
], - "custom51": [
- "fullAccess"
], - "custom52": [
- "fullAccess"
], - "custom53": [
- "fullAccess"
], - "custom54": [
- "fullAccess"
], - "custom55": [
- "fullAccess"
], - "custom56": [
- "fullAccess"
], - "custom57": [
- "fullAccess"
], - "custom58": [
- "fullAccess"
], - "custom59": [
- "fullAccess"
], - "custom60": [
- "fullAccess"
], - "custom61": [
- "fullAccess"
], - "custom62": [
- "fullAccess"
], - "custom63": [
- "fullAccess"
], - "custom64": [
- "fullAccess"
], - "custom65": [
- "fullAccess"
], - "custom66": [
- "fullAccess"
], - "custom67": [
- "fullAccess"
], - "custom68": [
- "fullAccess"
], - "custom69": [
- "fullAccess"
], - "custom70": [
- "fullAccess"
], - "custom71": [
- "fullAccess"
], - "custom72": [
- "fullAccess"
], - "custom73": [
- "fullAccess"
], - "custom74": [
- "fullAccess"
], - "custom75": [
- "fullAccess"
], - "custom76": [
- "fullAccess"
], - "custom77": [
- "fullAccess"
], - "custom78": [
- "fullAccess"
], - "custom79": [
- "fullAccess"
], - "custom80": [
- "fullAccess"
], - "custom81": [
- "fullAccess"
], - "custom82": [
- "fullAccess"
], - "custom83": [
- "fullAccess"
], - "custom84": [
- "fullAccess"
], - "custom85": [
- "fullAccess"
], - "custom86": [
- "fullAccess"
], - "custom87": [
- "fullAccess"
], - "custom88": [
- "fullAccess"
], - "custom89": [
- "fullAccess"
], - "custom90": [
- "fullAccess"
], - "custom91": [
- "fullAccess"
], - "custom92": [
- "fullAccess"
], - "custom93": [
- "fullAccess"
], - "custom94": [
- "fullAccess"
], - "custom95": [
- "fullAccess"
], - "custom96": [
- "fullAccess"
], - "custom97": [
- "fullAccess"
], - "custom98": [
- "fullAccess"
], - "custom99": [
- "fullAccess"
], - "custom100": [
- "fullAccess"
], - "custom101": [
- "fullAccess"
], - "custom102": [
- "fullAccess"
], - "custom103": [
- "fullAccess"
], - "custom104": [
- "fullAccess"
], - "custom105": [
- "fullAccess"
], - "custom106": [
- "fullAccess"
], - "custom107": [
- "fullAccess"
], - "custom108": [
- "fullAccess"
], - "custom109": [
- "fullAccess"
], - "custom110": [
- "fullAccess"
], - "custom111": [
- "fullAccess"
], - "custom112": [
- "fullAccess"
], - "custom113": [
- "fullAccess"
], - "custom114": [
- "fullAccess"
], - "custom115": [
- "fullAccess"
], - "custom116": [
- "fullAccess"
], - "custom117": [
- "fullAccess"
], - "custom118": [
- "fullAccess"
], - "custom119": [
- "fullAccess"
], - "custom120": [
- "fullAccess"
], - "custom121": [
- "fullAccess"
], - "custom122": [
- "fullAccess"
], - "custom123": [
- "fullAccess"
], - "custom124": [
- "fullAccess"
], - "custom125": [
- "fullAccess"
], - "custom126": [
- "fullAccess"
], - "custom127": [
- "fullAccess"
], - "custom128": [
- "fullAccess"
], - "custom129": [
- "fullAccess"
], - "custom130": [
- "fullAccess"
], - "custom131": [
- "fullAccess"
], - "custom132": [
- "fullAccess"
], - "custom133": [
- "fullAccess"
], - "custom134": [
- "fullAccess"
], - "custom135": [
- "fullAccess"
], - "custom136": [
- "fullAccess"
], - "custom137": [
- "fullAccess"
], - "custom138": [
- "fullAccess"
], - "custom139": [
- "fullAccess"
], - "custom140": [
- "fullAccess"
], - "custom141": [
- "fullAccess"
], - "custom142": [
- "fullAccess"
], - "custom143": [
- "fullAccess"
], - "custom144": [
- "fullAccess"
], - "custom145": [
- "fullAccess"
], - "custom146": [
- "fullAccess"
], - "custom147": [
- "fullAccess"
], - "custom148": [
- "fullAccess"
], - "custom149": [
- "fullAccess"
], - "custom150": [
- "fullAccess"
]
}, - "userStatus": null,
- "accessType": null,
- "accountPolicies": {
- "mustChangePassword": false,
- "canChangePassword": true,
- "expiresOn": null,
- "canModifyProfile": true,
- "canViewBuildingNetwork": null
}, - "systemPolicies": null,
- "accessSchedule": null,
- "userPrivileges": [ ],
- "rolePrivileges": [
- "manageDevicesAndSites",
- "viewMetasysStatus",
- "discardAcknowledgedEvents",
- "discardAllEvents",
- "snoozeAllEvents",
- "manageAuditHistory",
- "clearAuditHistory",
- "systemConfigurationTool",
- "scheduleReports",
- "mARSReportAccess"
]
}, - "roles": null,
- "userViews": {
- "userName": "jsmith",
- "id": "anNtaXRo",
- "userViews": [
- {
- "uniqueId": "55K UV KEEP"
}, - {
- "uniqueId": "8 Nested Folders"
}, - {
- "uniqueId": "B5F4"
}, - {
- "uniqueId": "Bad References"
}, - {
- "uniqueId": "Burst Alarms"
}, - {
- "uniqueId": "Diagnostics and Configuration"
}, - {
- "uniqueId": "EnergyEssentials"
}, - {
- "uniqueId": "MSTP New Jersey"
}, - {
- "uniqueId": "MSTP Points and Controllers"
}, - {
- "uniqueId": "N2 Points"
}, - {
- "uniqueId": "TECs New-Jersey"
}, - {
- "uniqueId": "Trend Studies"
}, - {
- "uniqueId": "Various AVs"
}, - {
- "uniqueId": "Various BVs"
}, - {
- "uniqueId": "Various Graphics"
}, - {
- "uniqueId": "Various Interlocks"
}, - {
- "uniqueId": "Various Schedules"
}
]
}
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Edit a user
| userId required | string Example: anNtaXRo The identifier of the user to retrieve. |
| userName | string |
object | |
object | |
object or null | |
object |
{- "userName": "api-user",
- "profile": {
- "id": "YXBpLXVzZXI",
- "description": "",
- "primaryPhone": "",
- "locale": "US",
- "language": "en",
- "totalRoles": null,
- "roles": null,
- "accessType": null,
- "isAudibleAlarmEnabled": true,
- "userDefined": true,
- "userName": "api-user",
- "fullName": "",
- "primaryEmail": "",
- "authenticationType": "metasys",
- "lastLogin": null,
- "accountStatus": null
}, - "permissions": {
- "id": "YXBpLXVzZXI",
- "userName": "api-user",
- "userType": null,
- "userPermissions": { },
- "rolePermissions": {
- "hvac": [
- "fullAccess"
], - "fire": [
- "fullAccess"
], - "security": [
- "fullAccess"
], - "services": [
- "fullAccess"
], - "administrative": [
- "fullAccess"
], - "general": [
- "fullAccess"
], - "lighting": [
- "fullAccess"
], - "refrigeration": [
- "fullAccess"
], - "criticalEnvironment": [
- "fullAccess"
], - "airQuality": [
- "fullAccess"
], - "power": [
- "fullAccess"
], - "energy": [
- "fullAccess"
], - "system": [
- "fullAccess"
], - "custom1": [
- "fullAccess"
], - "custom2": [
- "fullAccess"
], - "custom3": [
- "fullAccess"
], - "custom4": [
- "fullAccess"
], - "custom5": [
- "fullAccess"
], - "custom6": [
- "fullAccess"
], - "custom7": [
- "fullAccess"
], - "custom8": [
- "fullAccess"
], - "custom9": [
- "fullAccess"
], - "custom10": [
- "fullAccess"
], - "custom11": [
- "fullAccess"
], - "custom12": [
- "fullAccess"
], - "custom13": [
- "fullAccess"
], - "custom14": [
- "fullAccess"
], - "custom15": [
- "fullAccess"
], - "custom16": [
- "fullAccess"
], - "custom17": [
- "fullAccess"
], - "custom18": [
- "fullAccess"
], - "custom19": [
- "fullAccess"
], - "custom20": [
- "fullAccess"
], - "custom21": [
- "fullAccess"
], - "custom22": [
- "fullAccess"
], - "custom23": [
- "fullAccess"
], - "custom24": [
- "fullAccess"
], - "custom25": [
- "fullAccess"
], - "custom26": [
- "fullAccess"
], - "custom27": [
- "fullAccess"
], - "custom28": [
- "fullAccess"
], - "custom29": [
- "fullAccess"
], - "custom30": [
- "fullAccess"
], - "custom31": [
- "fullAccess"
], - "custom32": [
- "fullAccess"
], - "custom33": [
- "fullAccess"
], - "custom34": [
- "fullAccess"
], - "custom35": [
- "fullAccess"
], - "custom36": [
- "fullAccess"
], - "custom37": [
- "fullAccess"
], - "custom38": [
- "fullAccess"
], - "custom39": [
- "fullAccess"
], - "custom40": [
- "fullAccess"
], - "custom41": [
- "fullAccess"
], - "custom42": [
- "fullAccess"
], - "custom43": [
- "fullAccess"
], - "custom44": [
- "fullAccess"
], - "custom45": [
- "fullAccess"
], - "custom46": [
- "fullAccess"
], - "custom47": [
- "fullAccess"
], - "custom48": [
- "fullAccess"
], - "custom49": [
- "fullAccess"
], - "custom50": [
- "fullAccess"
], - "custom51": [
- "fullAccess"
], - "custom52": [
- "fullAccess"
], - "custom53": [
- "fullAccess"
], - "custom54": [
- "fullAccess"
], - "custom55": [
- "fullAccess"
], - "custom56": [
- "fullAccess"
], - "custom57": [
- "fullAccess"
], - "custom58": [
- "fullAccess"
], - "custom59": [
- "fullAccess"
], - "custom60": [
- "fullAccess"
], - "custom61": [
- "fullAccess"
], - "custom62": [
- "fullAccess"
], - "custom63": [
- "fullAccess"
], - "custom64": [
- "fullAccess"
], - "custom65": [
- "fullAccess"
], - "custom66": [
- "fullAccess"
], - "custom67": [
- "fullAccess"
], - "custom68": [
- "fullAccess"
], - "custom69": [
- "fullAccess"
], - "custom70": [
- "fullAccess"
], - "custom71": [
- "fullAccess"
], - "custom72": [
- "fullAccess"
], - "custom73": [
- "fullAccess"
], - "custom74": [
- "fullAccess"
], - "custom75": [
- "fullAccess"
], - "custom76": [
- "fullAccess"
], - "custom77": [
- "fullAccess"
], - "custom78": [
- "fullAccess"
], - "custom79": [
- "fullAccess"
], - "custom80": [
- "fullAccess"
], - "custom81": [
- "fullAccess"
], - "custom82": [
- "fullAccess"
], - "custom83": [
- "fullAccess"
], - "custom84": [
- "fullAccess"
], - "custom85": [
- "fullAccess"
], - "custom86": [
- "fullAccess"
], - "custom87": [
- "fullAccess"
], - "custom88": [
- "fullAccess"
], - "custom89": [
- "fullAccess"
], - "custom90": [
- "fullAccess"
], - "custom91": [
- "fullAccess"
], - "custom92": [
- "fullAccess"
], - "custom93": [
- "fullAccess"
], - "custom94": [
- "fullAccess"
], - "custom95": [
- "fullAccess"
], - "custom96": [
- "fullAccess"
], - "custom97": [
- "fullAccess"
], - "custom98": [
- "fullAccess"
], - "custom99": [
- "fullAccess"
], - "custom100": [
- "fullAccess"
], - "custom101": [
- "fullAccess"
], - "custom102": [
- "fullAccess"
], - "custom103": [
- "fullAccess"
], - "custom104": [
- "fullAccess"
], - "custom105": [
- "fullAccess"
], - "custom106": [
- "fullAccess"
], - "custom107": [
- "fullAccess"
], - "custom108": [
- "fullAccess"
], - "custom109": [
- "fullAccess"
], - "custom110": [
- "fullAccess"
], - "custom111": [
- "fullAccess"
], - "custom112": [
- "fullAccess"
], - "custom113": [
- "fullAccess"
], - "custom114": [
- "fullAccess"
], - "custom115": [
- "fullAccess"
], - "custom116": [
- "fullAccess"
], - "custom117": [
- "fullAccess"
], - "custom118": [
- "fullAccess"
], - "custom119": [
- "fullAccess"
], - "custom120": [
- "fullAccess"
], - "custom121": [
- "fullAccess"
], - "custom122": [
- "fullAccess"
], - "custom123": [
- "fullAccess"
], - "custom124": [
- "fullAccess"
], - "custom125": [
- "fullAccess"
], - "custom126": [
- "fullAccess"
], - "custom127": [
- "fullAccess"
], - "custom128": [
- "fullAccess"
], - "custom129": [
- "fullAccess"
], - "custom130": [
- "fullAccess"
], - "custom131": [
- "fullAccess"
], - "custom132": [
- "fullAccess"
], - "custom133": [
- "fullAccess"
], - "custom134": [
- "fullAccess"
], - "custom135": [
- "fullAccess"
], - "custom136": [
- "fullAccess"
], - "custom137": [
- "fullAccess"
], - "custom138": [
- "fullAccess"
], - "custom139": [
- "fullAccess"
], - "custom140": [
- "fullAccess"
], - "custom141": [
- "fullAccess"
], - "custom142": [
- "fullAccess"
], - "custom143": [
- "fullAccess"
], - "custom144": [
- "fullAccess"
], - "custom145": [
- "fullAccess"
], - "custom146": [
- "fullAccess"
], - "custom147": [
- "fullAccess"
], - "custom148": [
- "fullAccess"
], - "custom149": [
- "fullAccess"
], - "custom150": [
- "fullAccess"
]
}, - "userStatus": null,
- "accessType": null,
- "accountPolicies": {
- "mustChangePassword": false,
- "canChangePassword": true,
- "expiresOn": null,
- "canModifyProfile": true,
- "canViewBuildingNetwork": null
}, - "systemPolicies": null,
- "accessSchedule": null,
- "userPrivileges": [ ],
- "rolePrivileges": [
- "manageDevicesAndSites",
- "viewMetasysStatus",
- "discardAcknowledgedEvents",
- "discardAllEvents",
- "snoozeAllEvents",
- "manageAuditHistory",
- "clearAuditHistory",
- "systemConfigurationTool",
- "scheduleReports",
- "mARSReportAccess"
]
}, - "roles": null,
- "userViews": {
- "userName": "api-user",
- "id": "YXBpLXVzZXI",
- "userViews": [
- {
- "uniqueId": "User View - Shally"
}, - {
- "uniqueId": "User View Welch"
}, - {
- "uniqueId": "User View1"
}
]
}
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
Get information about the user account of the current session.
curl --request GET \ --url https://metasys-server.example.com/api/v5/userinfo \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "userName": "api-user",
- "profile": {
- "id": "YXBpLXVzZXI",
- "description": "",
- "primaryPhone": "",
- "locale": "US",
- "language": "en",
- "totalRoles": null,
- "roles": null,
- "accessType": null,
- "isAudibleAlarmEnabled": true,
- "userDefined": true,
- "userName": "api-user",
- "fullName": "",
- "primaryEmail": "",
- "authenticationType": "metasys",
- "lastLogin": null,
- "accountStatus": null
}, - "permissions": {
- "id": "YXBpLXVzZXI",
- "userName": "api-user",
- "userType": null,
- "userPermissions": { },
- "rolePermissions": {
- "hvac": [
- "fullAccess"
], - "fire": [
- "fullAccess"
], - "security": [
- "fullAccess"
], - "services": [
- "fullAccess"
], - "administrative": [
- "fullAccess"
], - "general": [
- "fullAccess"
], - "lighting": [
- "fullAccess"
], - "refrigeration": [
- "fullAccess"
], - "criticalEnvironment": [
- "fullAccess"
], - "airQuality": [
- "fullAccess"
], - "power": [
- "fullAccess"
], - "energy": [
- "fullAccess"
], - "system": [
- "fullAccess"
], - "custom1": [
- "fullAccess"
], - "custom2": [
- "fullAccess"
], - "custom3": [
- "fullAccess"
], - "custom4": [
- "fullAccess"
], - "custom5": [
- "fullAccess"
], - "custom6": [
- "fullAccess"
], - "custom7": [
- "fullAccess"
], - "custom8": [
- "fullAccess"
], - "custom9": [
- "fullAccess"
], - "custom10": [
- "fullAccess"
], - "custom11": [
- "fullAccess"
], - "custom12": [
- "fullAccess"
], - "custom13": [
- "fullAccess"
], - "custom14": [
- "fullAccess"
], - "custom15": [
- "fullAccess"
], - "custom16": [
- "fullAccess"
], - "custom17": [
- "fullAccess"
], - "custom18": [
- "fullAccess"
], - "custom19": [
- "fullAccess"
], - "custom20": [
- "fullAccess"
], - "custom21": [
- "fullAccess"
], - "custom22": [
- "fullAccess"
], - "custom23": [
- "fullAccess"
], - "custom24": [
- "fullAccess"
], - "custom25": [
- "fullAccess"
], - "custom26": [
- "fullAccess"
], - "custom27": [
- "fullAccess"
], - "custom28": [
- "fullAccess"
], - "custom29": [
- "fullAccess"
], - "custom30": [
- "fullAccess"
], - "custom31": [
- "fullAccess"
], - "custom32": [
- "fullAccess"
], - "custom33": [
- "fullAccess"
], - "custom34": [
- "fullAccess"
], - "custom35": [
- "fullAccess"
], - "custom36": [
- "fullAccess"
], - "custom37": [
- "fullAccess"
], - "custom38": [
- "fullAccess"
], - "custom39": [
- "fullAccess"
], - "custom40": [
- "fullAccess"
], - "custom41": [
- "fullAccess"
], - "custom42": [
- "fullAccess"
], - "custom43": [
- "fullAccess"
], - "custom44": [
- "fullAccess"
], - "custom45": [
- "fullAccess"
], - "custom46": [
- "fullAccess"
], - "custom47": [
- "fullAccess"
], - "custom48": [
- "fullAccess"
], - "custom49": [
- "fullAccess"
], - "custom50": [
- "fullAccess"
], - "custom51": [
- "fullAccess"
], - "custom52": [
- "fullAccess"
], - "custom53": [
- "fullAccess"
], - "custom54": [
- "fullAccess"
], - "custom55": [
- "fullAccess"
], - "custom56": [
- "fullAccess"
], - "custom57": [
- "fullAccess"
], - "custom58": [
- "fullAccess"
], - "custom59": [
- "fullAccess"
], - "custom60": [
- "fullAccess"
], - "custom61": [
- "fullAccess"
], - "custom62": [
- "fullAccess"
], - "custom63": [
- "fullAccess"
], - "custom64": [
- "fullAccess"
], - "custom65": [
- "fullAccess"
], - "custom66": [
- "fullAccess"
], - "custom67": [
- "fullAccess"
], - "custom68": [
- "fullAccess"
], - "custom69": [
- "fullAccess"
], - "custom70": [
- "fullAccess"
], - "custom71": [
- "fullAccess"
], - "custom72": [
- "fullAccess"
], - "custom73": [
- "fullAccess"
], - "custom74": [
- "fullAccess"
], - "custom75": [
- "fullAccess"
], - "custom76": [
- "fullAccess"
], - "custom77": [
- "fullAccess"
], - "custom78": [
- "fullAccess"
], - "custom79": [
- "fullAccess"
], - "custom80": [
- "fullAccess"
], - "custom81": [
- "fullAccess"
], - "custom82": [
- "fullAccess"
], - "custom83": [
- "fullAccess"
], - "custom84": [
- "fullAccess"
], - "custom85": [
- "fullAccess"
], - "custom86": [
- "fullAccess"
], - "custom87": [
- "fullAccess"
], - "custom88": [
- "fullAccess"
], - "custom89": [
- "fullAccess"
], - "custom90": [
- "fullAccess"
], - "custom91": [
- "fullAccess"
], - "custom92": [
- "fullAccess"
], - "custom93": [
- "fullAccess"
], - "custom94": [
- "fullAccess"
], - "custom95": [
- "fullAccess"
], - "custom96": [
- "fullAccess"
], - "custom97": [
- "fullAccess"
], - "custom98": [
- "fullAccess"
], - "custom99": [
- "fullAccess"
], - "custom100": [
- "fullAccess"
], - "custom101": [
- "fullAccess"
], - "custom102": [
- "fullAccess"
], - "custom103": [
- "fullAccess"
], - "custom104": [
- "fullAccess"
], - "custom105": [
- "fullAccess"
], - "custom106": [
- "fullAccess"
], - "custom107": [
- "fullAccess"
], - "custom108": [
- "fullAccess"
], - "custom109": [
- "fullAccess"
], - "custom110": [
- "fullAccess"
], - "custom111": [
- "fullAccess"
], - "custom112": [
- "fullAccess"
], - "custom113": [
- "fullAccess"
], - "custom114": [
- "fullAccess"
], - "custom115": [
- "fullAccess"
], - "custom116": [
- "fullAccess"
], - "custom117": [
- "fullAccess"
], - "custom118": [
- "fullAccess"
], - "custom119": [
- "fullAccess"
], - "custom120": [
- "fullAccess"
], - "custom121": [
- "fullAccess"
], - "custom122": [
- "fullAccess"
], - "custom123": [
- "fullAccess"
], - "custom124": [
- "fullAccess"
], - "custom125": [
- "fullAccess"
], - "custom126": [
- "fullAccess"
], - "custom127": [
- "fullAccess"
], - "custom128": [
- "fullAccess"
], - "custom129": [
- "fullAccess"
], - "custom130": [
- "fullAccess"
], - "custom131": [
- "fullAccess"
], - "custom132": [
- "fullAccess"
], - "custom133": [
- "fullAccess"
], - "custom134": [
- "fullAccess"
], - "custom135": [
- "fullAccess"
], - "custom136": [
- "fullAccess"
], - "custom137": [
- "fullAccess"
], - "custom138": [
- "fullAccess"
], - "custom139": [
- "fullAccess"
], - "custom140": [
- "fullAccess"
], - "custom141": [
- "fullAccess"
], - "custom142": [
- "fullAccess"
], - "custom143": [
- "fullAccess"
], - "custom144": [
- "fullAccess"
], - "custom145": [
- "fullAccess"
], - "custom146": [
- "fullAccess"
], - "custom147": [
- "fullAccess"
], - "custom148": [
- "fullAccess"
], - "custom149": [
- "fullAccess"
], - "custom150": [
- "fullAccess"
]
}, - "userStatus": null,
- "accessType": null,
- "accountPolicies": {
- "mustChangePassword": false,
- "canChangePassword": true,
- "expiresOn": null,
- "canModifyProfile": true,
- "canViewBuildingNetwork": null
}, - "systemPolicies": null,
- "accessSchedule": null,
- "userPrivileges": [ ],
- "rolePrivileges": [
- "manageDevicesAndSites",
- "viewMetasysStatus",
- "discardAcknowledgedEvents",
- "discardAllEvents",
- "snoozeAllEvents",
- "manageAuditHistory",
- "clearAuditHistory",
- "systemConfigurationTool",
- "scheduleReports",
- "mARSReportAccess"
]
}, - "roles": null,
- "userViews": {
- "userName": "api-user",
- "id": "YXBpLXVzZXI",
- "userViews": [
- {
- "uniqueId": "User View - Shally"
}, - {
- "uniqueId": "User View Welch"
}, - {
- "uniqueId": "User View1"
}
]
}
}The set of dummy operations used only to get validation of our server-sent events. These should all be hidden visibility.
Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all active subscriptionIds for this stream |
{- "currentTime": "2022-01-01T00:00:00Z",
- "subscriptionIds": [
- "34a22b98-9bfc-41d3-a275-933e5977c447"
]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all active subscriptionIds for this stream |
required | Array of objects The collection of available items. |
| total required | integer The total number of items in the collection |
{- "subscriptionIds": [
- "7bd86189-3129-4463-841d-b2ad598fa4fd"
], - "message": "Sample subscription successful",
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "sampledObjects": [
- {
- "sampledObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "attribute": "presentValue",
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "sampledByObjectId": {
- "type": "string"
}, - "sampledObjectId": {
- "type": "string"
}, - "attribute": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}, - "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.noUnits",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}
}
]
}
], - "total": 1
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all subscription Ids for this stream for whom errors have been generated. |
required | Array of objects The collection of available error items. |
| total required | integer The total number of items in the collection |
{- "subscriptionIds": [
- "68edbb25-00f0-4bcf-8008-235eab1d7bbc"
], - "message": "There was an issue in retrieving samples",
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "code": "api:error.internalFault",
- "message": "The endpoint encountered an internal fault"
}
], - "total": 1
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all subscriptionIds for this stream which have been cancelled. |
| message required | string The display string message that correlates to the subscriptions that have been cancelled. |
{- "subscriptionIds": [
- "b287344d-2d57-45c1-a9f2-1ec954a36984"
], - "message": "Sample subscription cancelled"
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all subscription IDs that the updates apply to for this stream |
| total required | integer The total number of items in the collection |
required | Array of objects A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to. |
{- "subscriptionIds": [
- "b287344d-2d57-45c1-a9f2-1ec954a36984"
], - "total": 2,
- "items": [
- {
- "sampledByObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "sampledObjectId": "08853b47-e0d9-54f6-8e0b-4976dcd38a03",
- "attribute": "presentValue",
- "value": -10,
- "sampleTime": "2023-05-05T10:07:00Z",
- "reliability": "reliabilityEnumSet.reliable"
}, - {
- "sampledByObjectId": "20a2fd2c-168f-502c-8221-db862d866402",
- "sampledObjectId": "831147e1-8dc7-5aa9-ac92-541fce8ab7b5",
- "attribute": "presentValue",
- "value": "binarypvEnumSet.bacbinInactive",
- "sampleTime": "2023-05-05T18:24:00Z",
- "reliability": "reliabilityEnumSet.reliable"
}
]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all subscriptionIds for this async stream which an error has been generated, |
| message required | string The display string message that correlates to an error has occurred in async stream. |
{- "subscriptionIds": [
- "9c50fe10-a958-4bd4-b29f-0c4ac82c74bb"
], - "message": "An error occurred while streaming samples."
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all subscriptionIds for this async stream which has been completed. |
| message required | string The display string message that correlates to the completion of an async samples response. |
{- "subscriptionIds": [
- "9c50fe10-a958-4bd4-b29f-0c4ac82c74bb"
], - "message": "Samples stream response completed"
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings List of all active subscriptionIds for this stream |
{- "currentTime": "2022-01-01T00:00:00Z",
- "subscriptionIds": [
- "34a22b98-9bfc-41d3-a275-933e5977c447"
]
}Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.
undefined
| subscriptionIds required | Array of strings <uuid> [ items <uuid > ] Subscription IDs that the notification apply to |
| total required | integer <int32> Total alarms pending acknowledgement |
object or null Current priority alarm. If null and |
{- "subscriptionIds": [
- "34a22b98-9bfc-41d3-a275-933e5977c447"
], - "total": 5,
- "item": {
- "id": "cedcf9f2-5ee5-445a-8f27-86997e3f7bc5",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "description": "Analog Value",
- "name": "AV1",
- "associatedGraphic": {
- "reference": {
- "objectReference": "{hostname}:{deviceHostname}"
}, - "alias": "AV*"
}, - "message": "Alarm message",
- "type": "alarmValueEnumSet.avHiAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2022-08-15T18:39:50Z",
}
}